spaps-sdk 1.13.0 → 1.13.2

package/CHANGELOG.md

@@ -6,6 +6,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
+- No changes yet.
+
+## [1.13.1] - 2026-06-20
+
 ### Added
 
 - Added `whitelist`, `users`, and `supportTelemetry` namespaces so the TypeScript SDK matches consumer-facing Python client domain coverage.

package/README.md

@@ -679,7 +679,7 @@ npm run test:readme
 ## Metadata
 
 - `package_name`: `spaps-sdk`
-- `latest_version`: `1.13.0`
+- `latest_version`: `1.13.1`
 - `minimum_runtime`: `Node.js >=14.0.0`
 - `api_base_url`: `https://api.sweetpotato.dev`
 

package/dist/index.d.mts

@@ -186,6 +186,28 @@ interface WebSocketAuthHelperConfig {
      * Should perform the refresh and return the new access token.
      */
     refreshAccessToken: () => Promise<string>;
+    /**
+     * Optional: mint a short-lived, single-use WebSocket connect ticket.
+     *
+     * When provided, the helper opens the socket with `?ticket=<ticket>` instead
+     * of placing any long-lived credential in the URL. This is the preferred,
+     * server-aligned path: it matches SPAPS `POST /realtime/ws-ticket`, whose
+     * tickets are single-use and expire in seconds, so a leak via logs / proxies
+     * / referrers is inert. A fresh ticket is minted for every connection attempt
+     * (including reconnects), because each ticket is consumed on use.
+     *
+     * When omitted, the helper falls back to carrying the bearer token in the
+     * WebSocket subprotocol (the `Sec-WebSocket-Protocol` handshake header) rather
+     * than the URL query string — so the long-lived JWT is never logged. The
+     * server must read the subprotocol for the fallback to authenticate.
+     */
+    getConnectTicket?: () => Promise<string> | string;
+    /**
+     * Milliseconds to wait for the socket to open before rejecting `connect()`.
+     * Prevents `connect()` from hanging forever when the socket never opens.
+     * 0 disables the timeout (default 10000).
+     */
+    connectTimeoutMs?: number;
     /** Seconds before token expiry to proactively refresh (default 30). */
     refreshBufferSeconds?: number;
     /** Maximum number of reconnection attempts on auth failures (default 3). */
@@ -218,7 +240,11 @@ declare class WebSocketAuthHelper {
     constructor(config: WebSocketAuthHelperConfig);
     /**
      * Open an authenticated WebSocket connection.
-     * Appends the access token as a query parameter.
+     *
+     * The long-lived access token is never placed in the URL. Authentication uses
+     * a short-lived single-use connect ticket (`?ticket=...`) when
+     * `getConnectTicket` is configured, otherwise the bearer token is carried in
+     * the WebSocket subprotocol (handshake header).
      */
     connect(): Promise<void>;
     /**
@@ -230,8 +256,23 @@ declare class WebSocketAuthHelper {
      * Throws if the connection is not open.
      */
     send(data: string): void;
-    /** Build the authenticated WebSocket URL. */
-    buildAuthUrl(): string;
+    /**
+     * Build the WebSocket URL.
+     *
+     * Never embeds the long-lived access token. When a short-lived connect
+     * `ticket` is supplied it is appended as `?ticket=<ticket>` (single-use,
+     * seconds-long TTL — inert if leaked). Otherwise the bare base URL is
+     * returned and the credential travels in the subprotocol instead.
+     */
+    buildAuthUrl(ticket?: string): string;
+    /**
+     * Build the WebSocket subprotocols carrying the bearer credential.
+     *
+     * Used only by the no-ticket fallback so the long-lived JWT travels in the
+     * `Sec-WebSocket-Protocol` handshake header rather than the URL query string.
+     * Throws when no access token is available.
+     */
+    buildAuthProtocols(): string[];
     private openConnection;
     private handleAuthClose;
     private handleNetworkClose;
@@ -301,6 +342,7 @@ interface EmailSendOptions {
     to: string;
     context: Record<string, string | number | boolean>;
     userId?: string;
+    idempotencyKey?: string;
 }
 interface EmailSendResult {
     success: boolean;
@@ -678,17 +720,22 @@ interface ListMembershipsParams {
     cursor?: string;
 }
 interface SupportActor {
-    type: string;
+    type: SupportActorType;
     id?: string | null;
 }
+type SupportActorType = 'user' | 'practitioner' | 'anonymous' | 'service' | 'support_operator';
+type SupportCaseStatus = 'open' | 'in_progress' | 'resolved' | 'ignored';
+type SupportCasePriority = 'low' | 'normal' | 'high' | 'urgent';
+type SupportEventSeverity = 'info' | 'warning' | 'error' | 'critical';
+type SupportSourceChannel = 'issue_log' | 'support_thread' | 'email' | 'frontend' | 'api' | 'webhook';
 interface SupportCaseSummary {
     id: string;
     application_id: string;
     external_case_ref?: string | null;
     title?: string | null;
-    status: string;
-    priority: string;
-    highest_severity: string;
+    status: SupportCaseStatus;
+    priority: SupportCasePriority;
+    highest_severity: SupportEventSeverity;
     assigned_to_user_id?: string | null;
     first_event_at: string;
     last_event_at: string;
@@ -700,9 +747,9 @@ interface SupportCaseEvent {
     id: string;
     case_id: string;
     event_key: string;
-    source_channel: string;
+    source_channel: SupportSourceChannel;
     event_type: string;
-    severity: string;
+    severity: SupportEventSeverity;
     actor: SupportActor;
     correlation_id?: string | null;
     occurred_at: string;
@@ -712,9 +759,9 @@ interface SupportCaseEvent {
 interface SupportTelemetryIngestRequest {
     event_key: string;
     occurred_at: string;
-    source_channel: string;
+    source_channel: SupportSourceChannel;
     event_type: string;
-    severity: string;
+    severity: SupportEventSeverity;
     actor: SupportActor;
     payload: Record<string, unknown>;
     application_id?: string | null;
@@ -727,13 +774,13 @@ interface SupportTelemetryIngestResponse {
     case_id: string;
     created_case: boolean;
     deduplicated: boolean;
-    case_status: string;
+    case_status: SupportCaseStatus;
 }
 interface SupportTelemetryListCasesParams {
     application_id?: string;
-    status?: string;
-    priority?: string;
-    severity_gte?: string;
+    status?: SupportCaseStatus;
+    priority?: SupportCasePriority;
+    severity_gte?: SupportEventSeverity;
     assigned_to_user_id?: string;
     limit?: number;
     offset?: number;
@@ -748,16 +795,16 @@ interface SupportTelemetryCaseDetailResponse {
     event_total: number;
 }
 interface SupportTelemetryPatchCaseRequest {
-    status?: string;
-    priority?: string;
+    status?: SupportCaseStatus;
+    priority?: SupportCasePriority;
     assigned_to_user_id?: string | null;
     resolution_note?: string | null;
 }
 interface SupportTelemetryPatchCaseResponse {
     case: {
         id: string;
-        status: string;
-        priority: string;
+        status: SupportCaseStatus;
+        priority: SupportCasePriority;
         assigned_to_user_id?: string | null;
         resolved_at?: string | null;
         updated_at: string;
@@ -768,8 +815,8 @@ interface SupportTelemetryCaseByExternalResponse {
         id: string;
         application_id: string;
         external_case_ref?: string | null;
-        status: string;
-        priority: string;
+        status: SupportCaseStatus;
+        priority: SupportCasePriority;
         assigned_to_user_id?: string | null;
         resolved_at?: string | null;
         updated_at: string;
@@ -1390,9 +1437,21 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
     private normalizeAuthPayload;
     private storeAuthTokens;
     private unwrapAuthMethodResponse;
+    /**
+     * Unwrap the SPAPS `{ success, data }` response envelope for the legacy
+     * token-issuing auth methods (login/register/walletSignIn/refresh).
+     *
+     * The server's ResponseEnvelopeMiddleware wraps these responses, so the real
+     * tokens live at `response.data.data`. Reading `response.data.access_token`
+     * (one level too shallow) silently dropped the tokens. Reuse the shared
+     * `unwrapApiResponse` primitive so envelope handling and error fidelity stay
+     * consistent with the rest of the client.
+     */
+    private extractAuthResponse;
     private static isSdkManagedHeader;
     private static hasHeader;
     private static setHeader;
+    private static deleteHeader;
     private static assertSafeHeaderValue;
     private applyCustomHeaders;
     admin: {
@@ -1745,7 +1804,7 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
         register: (payload: {
             email: string;
             password: string;
-        }) => Promise<any>;
+        }) => Promise<AuthMethodResponse>;
         /**
          * Verify a magic link token and authenticate the user.
          * Returns full auth response with tokens and auto-stores them.
@@ -2282,4 +2341,4 @@ declare function createServerClient(secretKey: string, options?: Omit<SPAPSConfi
  */
 declare function detectKeyType(key: string): ApiKeyType | null;
 
-export { type AccessDecisionRequest, type AccessDecisionResponse, type AccountDeletionResponse, type ActionPreparationRequest, type ActionPreparationResponse, type AdminConfig, type ApiKeyType, type AuthDiscoveryMethod, type AuthMethodDescriptor, type AuthMethodResponse, type AuthMethodsResponse, type BatchEmailsResponse, type BatchUsersResponse, type CapabilityActionEnvironment, type CapabilityControlHints, type CapabilityDecisionActor, type CapabilityDecisionFact, type CapabilityDecisionNextAction, type CapabilityDecisionOutcome, type CapabilityDecisionReason, type CapabilityDecisionResource, type CapabilityDecisionSource, type CapabilityGraphContractResponse, type CapabilityGraphImpactQuery, type CapabilityGraphImpactResponse, type CapabilityGraphNode, type CapabilityGraphNodesQuery, type CapabilityGraphNodesResponse, type CapabilityGraphPath, type CapabilityGraphPathsQuery, type CapabilityGraphPathsResponse, type CapabilityGraphProjectionStatus, type CapabilityGraphRefreshDiagnostics, type CapabilityGraphRefreshPhase2Gate, type CapabilityGraphRefreshResponse, type CapabilityGraphRefreshSourceTiming, type CapabilityGraphRowStatus, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, type CreateSkillEvalCaseRequest, type CreateSkillEvalGovernanceSnapshotRequest, type CurrentUserProjectAccessParams, type CurrentUserProjectGrantListParams, DEFAULT_ADMIN_ACCOUNTS, type EmailSendOptions, type EmailSendResult, type EmailTemplate, type EmailTemplatePreview, type EntitlementCheckResult, type EntitlementListParams, type FeatureContext, type FeatureDefinition, FeatureEvaluator, type GraphExplainResponse, type HeaderProvider, ISSUE_REPORT_ATTACHMENT_ALLOWED_MIME_TYPES, ISSUE_REPORT_ATTACHMENT_MAX_BYTES, ISSUE_REPORT_ATTACHMENT_MAX_RETAINED, type ImportSkillEvalGovernanceOutcomeRequest, type IssueReportAttachmentMimeType, type IssueReportAttachmentUploadOptions, type IssueReportListParams, type IssueReportStatusParams, type ListMembershipsParams, type ListMembershipsResponse, type MarketingEventIngestRequest, type MarketingEventIngestResponse, type MarketingEventType, type MarketingExperimentDecision, type MarketingExperimentEffectDecision, type MarketingExperimentMinSampleDecision, type MarketingExperimentRecommendation, type MarketingExperimentResultsResponse, type MarketingExperimentSrmDecision, type MarketingExperimentSrmStatus, type MarketingExperimentVariantResult, type Membership, type MembershipInvitation, type MembershipMutationRequest, type MembershipMutationResponse, type MembershipRemoveResponse, type MembershipStatus, type MfaRequiredAuthResponse, type MfaTotpActivateRequest, type MfaTotpActivateResponse, type MfaTotpDisableRequest, type MfaTotpDisableResponse, type MfaTotpEnrollResponse, type MfaVerifyRequest, type MfaVerifyResponse, type OidcNonceResponse, type OidcSignInRequest, type PermissionCheckResult, PermissionChecker, type PersistedDecisionTrace, type PersistedDecisionTraceStep, type PreparedCapabilityActionStatus, type PreparedCapabilityExecution, type PreparedCapabilityNextAction, type PreparedCapabilitySideEffect, type RespondToSkillEvalReviewRequest, type RevealSkillEvalEvidenceRequest, RoleHierarchy, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type SPAPSEnvelope, type SPAPSErrorDiagnostic, type SPAPSErrorRemediation, SPAPSSDKError, type SPAPSSDKErrorOptions, type SessionContext, type SkillEvalAccessMode, type SkillEvalActorAccess, type SkillEvalCandidateInput, type SkillEvalCandidateResponse, type SkillEvalCasePolicy, type SkillEvalCaseResponse, type SkillEvalConfidence, type SkillEvalCreateOptions, type SkillEvalDisclosurePolicy, type SkillEvalEligibilitySource, type SkillEvalGovernanceOutcomeResult, type SkillEvalGovernancePurpose, type SkillEvalGovernanceSnapshotResult, type SkillEvalInsight, type SkillEvalInsightsResponse, type SkillEvalModelEffort, type SkillEvalMutationOptions, type SkillEvalPosterResponse, type SkillEvalPosterResponseResult, type SkillEvalRevealField, type SkillEvalRevealResult, type SkillEvalReviewMarkInput, type SkillEvalReviewMarkKind, type SkillEvalReviewResponse, type SkillEvalReviewRoom, type SkillEvalReviewerEligibilityInput, type SkillEvalRewardEvent, type SmsOtpRequest, type SmsOtpRequestResponse, type SmsOtpVerifyRequest, type SubmitSkillEvalReviewRequest, type SupportActor, type SupportCaseEvent, type SupportCaseSummary, type SupportTelemetryCaseByExternalResponse, type SupportTelemetryCaseDetailResponse, type SupportTelemetryIngestRequest, type SupportTelemetryIngestResponse, type SupportTelemetryListCasesParams, type SupportTelemetryListCasesResponse, type SupportTelemetryPatchCaseRequest, type SupportTelemetryPatchCaseResponse, type TemplateVariable, TokenManager, type UserBatchInfo, WalletUtils, type WebAuthnAssertionOptionsRequest, type WebAuthnAssertionVerifyRequest, type WebAuthnOptionsResponse, type WebAuthnRegisterVerifyRequest, type WebAuthnRegisterVerifyResponse, WebSocketAuthHelper, type WebSocketAuthHelperConfig, type WhitelistAddRequest, type WhitelistBulkAddRequest, type WhitelistBulkAddResponse, type WhitelistBulkEntry, type WhitelistBulkFailedEntry, type WhitelistCheckResponse, type WhitelistEntry, type WhitelistListParams, type WhitelistListResponse, type WhitelistMutationResponse, type WhitelistStatsResponse, type WhitelistUpdateRequest, type X402ExecuteActionOptions, X402PaymentRequiredSDKError, type X402ReceiptListParams, type X402VerifyHandoffOptions, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, isEnvelope, isErrorEnvelope, isSuccessEnvelope, unwrapEnvelope, unwrapNestedData, verifyCryptoWebhookSignature };
+export { type AccessDecisionRequest, type AccessDecisionResponse, type AccountDeletionResponse, type ActionPreparationRequest, type ActionPreparationResponse, type AdminConfig, type ApiKeyType, type AuthDiscoveryMethod, type AuthMethodDescriptor, type AuthMethodResponse, type AuthMethodsResponse, type BatchEmailsResponse, type BatchUsersResponse, type CapabilityActionEnvironment, type CapabilityControlHints, type CapabilityDecisionActor, type CapabilityDecisionFact, type CapabilityDecisionNextAction, type CapabilityDecisionOutcome, type CapabilityDecisionReason, type CapabilityDecisionResource, type CapabilityDecisionSource, type CapabilityGraphContractResponse, type CapabilityGraphImpactQuery, type CapabilityGraphImpactResponse, type CapabilityGraphNode, type CapabilityGraphNodesQuery, type CapabilityGraphNodesResponse, type CapabilityGraphPath, type CapabilityGraphPathsQuery, type CapabilityGraphPathsResponse, type CapabilityGraphProjectionStatus, type CapabilityGraphRefreshDiagnostics, type CapabilityGraphRefreshPhase2Gate, type CapabilityGraphRefreshResponse, type CapabilityGraphRefreshSourceTiming, type CapabilityGraphRowStatus, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, type CreateSkillEvalCaseRequest, type CreateSkillEvalGovernanceSnapshotRequest, type CurrentUserProjectAccessParams, type CurrentUserProjectGrantListParams, DEFAULT_ADMIN_ACCOUNTS, type EmailSendOptions, type EmailSendResult, type EmailTemplate, type EmailTemplatePreview, type EntitlementCheckResult, type EntitlementListParams, type FeatureContext, type FeatureDefinition, FeatureEvaluator, type GraphExplainResponse, type HeaderProvider, ISSUE_REPORT_ATTACHMENT_ALLOWED_MIME_TYPES, ISSUE_REPORT_ATTACHMENT_MAX_BYTES, ISSUE_REPORT_ATTACHMENT_MAX_RETAINED, type ImportSkillEvalGovernanceOutcomeRequest, type IssueReportAttachmentMimeType, type IssueReportAttachmentUploadOptions, type IssueReportListParams, type IssueReportStatusParams, type ListMembershipsParams, type ListMembershipsResponse, type MarketingEventIngestRequest, type MarketingEventIngestResponse, type MarketingEventType, type MarketingExperimentDecision, type MarketingExperimentEffectDecision, type MarketingExperimentMinSampleDecision, type MarketingExperimentRecommendation, type MarketingExperimentResultsResponse, type MarketingExperimentSrmDecision, type MarketingExperimentSrmStatus, type MarketingExperimentVariantResult, type Membership, type MembershipInvitation, type MembershipMutationRequest, type MembershipMutationResponse, type MembershipRemoveResponse, type MembershipStatus, type MfaRequiredAuthResponse, type MfaTotpActivateRequest, type MfaTotpActivateResponse, type MfaTotpDisableRequest, type MfaTotpDisableResponse, type MfaTotpEnrollResponse, type MfaVerifyRequest, type MfaVerifyResponse, type OidcNonceResponse, type OidcSignInRequest, type PermissionCheckResult, PermissionChecker, type PersistedDecisionTrace, type PersistedDecisionTraceStep, type PreparedCapabilityActionStatus, type PreparedCapabilityExecution, type PreparedCapabilityNextAction, type PreparedCapabilitySideEffect, type RespondToSkillEvalReviewRequest, type RevealSkillEvalEvidenceRequest, RoleHierarchy, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type SPAPSEnvelope, type SPAPSErrorDiagnostic, type SPAPSErrorRemediation, SPAPSSDKError, type SPAPSSDKErrorOptions, type SessionContext, type SkillEvalAccessMode, type SkillEvalActorAccess, type SkillEvalCandidateInput, type SkillEvalCandidateResponse, type SkillEvalCasePolicy, type SkillEvalCaseResponse, type SkillEvalConfidence, type SkillEvalCreateOptions, type SkillEvalDisclosurePolicy, type SkillEvalEligibilitySource, type SkillEvalGovernanceOutcomeResult, type SkillEvalGovernancePurpose, type SkillEvalGovernanceSnapshotResult, type SkillEvalInsight, type SkillEvalInsightsResponse, type SkillEvalModelEffort, type SkillEvalMutationOptions, type SkillEvalPosterResponse, type SkillEvalPosterResponseResult, type SkillEvalRevealField, type SkillEvalRevealResult, type SkillEvalReviewMarkInput, type SkillEvalReviewMarkKind, type SkillEvalReviewResponse, type SkillEvalReviewRoom, type SkillEvalReviewerEligibilityInput, type SkillEvalRewardEvent, type SmsOtpRequest, type SmsOtpRequestResponse, type SmsOtpVerifyRequest, type SubmitSkillEvalReviewRequest, type SupportActor, type SupportActorType, type SupportCaseEvent, type SupportCasePriority, type SupportCaseStatus, type SupportCaseSummary, type SupportEventSeverity, type SupportSourceChannel, type SupportTelemetryCaseByExternalResponse, type SupportTelemetryCaseDetailResponse, type SupportTelemetryIngestRequest, type SupportTelemetryIngestResponse, type SupportTelemetryListCasesParams, type SupportTelemetryListCasesResponse, type SupportTelemetryPatchCaseRequest, type SupportTelemetryPatchCaseResponse, type TemplateVariable, TokenManager, type UserBatchInfo, WalletUtils, type WebAuthnAssertionOptionsRequest, type WebAuthnAssertionVerifyRequest, type WebAuthnOptionsResponse, type WebAuthnRegisterVerifyRequest, type WebAuthnRegisterVerifyResponse, WebSocketAuthHelper, type WebSocketAuthHelperConfig, type WhitelistAddRequest, type WhitelistBulkAddRequest, type WhitelistBulkAddResponse, type WhitelistBulkEntry, type WhitelistBulkFailedEntry, type WhitelistCheckResponse, type WhitelistEntry, type WhitelistListParams, type WhitelistListResponse, type WhitelistMutationResponse, type WhitelistStatsResponse, type WhitelistUpdateRequest, type X402ExecuteActionOptions, X402PaymentRequiredSDKError, type X402ReceiptListParams, type X402VerifyHandoffOptions, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, isEnvelope, isErrorEnvelope, isSuccessEnvelope, unwrapEnvelope, unwrapNestedData, verifyCryptoWebhookSignature };

package/dist/index.d.ts

@@ -186,6 +186,28 @@ interface WebSocketAuthHelperConfig {
      * Should perform the refresh and return the new access token.
      */
     refreshAccessToken: () => Promise<string>;
+    /**
+     * Optional: mint a short-lived, single-use WebSocket connect ticket.
+     *
+     * When provided, the helper opens the socket with `?ticket=<ticket>` instead
+     * of placing any long-lived credential in the URL. This is the preferred,
+     * server-aligned path: it matches SPAPS `POST /realtime/ws-ticket`, whose
+     * tickets are single-use and expire in seconds, so a leak via logs / proxies
+     * / referrers is inert. A fresh ticket is minted for every connection attempt
+     * (including reconnects), because each ticket is consumed on use.
+     *
+     * When omitted, the helper falls back to carrying the bearer token in the
+     * WebSocket subprotocol (the `Sec-WebSocket-Protocol` handshake header) rather
+     * than the URL query string — so the long-lived JWT is never logged. The
+     * server must read the subprotocol for the fallback to authenticate.
+     */
+    getConnectTicket?: () => Promise<string> | string;
+    /**
+     * Milliseconds to wait for the socket to open before rejecting `connect()`.
+     * Prevents `connect()` from hanging forever when the socket never opens.
+     * 0 disables the timeout (default 10000).
+     */
+    connectTimeoutMs?: number;
     /** Seconds before token expiry to proactively refresh (default 30). */
     refreshBufferSeconds?: number;
     /** Maximum number of reconnection attempts on auth failures (default 3). */
@@ -218,7 +240,11 @@ declare class WebSocketAuthHelper {
     constructor(config: WebSocketAuthHelperConfig);
     /**
      * Open an authenticated WebSocket connection.
-     * Appends the access token as a query parameter.
+     *
+     * The long-lived access token is never placed in the URL. Authentication uses
+     * a short-lived single-use connect ticket (`?ticket=...`) when
+     * `getConnectTicket` is configured, otherwise the bearer token is carried in
+     * the WebSocket subprotocol (handshake header).
      */
     connect(): Promise<void>;
     /**
@@ -230,8 +256,23 @@ declare class WebSocketAuthHelper {
      * Throws if the connection is not open.
      */
     send(data: string): void;
-    /** Build the authenticated WebSocket URL. */
-    buildAuthUrl(): string;
+    /**
+     * Build the WebSocket URL.
+     *
+     * Never embeds the long-lived access token. When a short-lived connect
+     * `ticket` is supplied it is appended as `?ticket=<ticket>` (single-use,
+     * seconds-long TTL — inert if leaked). Otherwise the bare base URL is
+     * returned and the credential travels in the subprotocol instead.
+     */
+    buildAuthUrl(ticket?: string): string;
+    /**
+     * Build the WebSocket subprotocols carrying the bearer credential.
+     *
+     * Used only by the no-ticket fallback so the long-lived JWT travels in the
+     * `Sec-WebSocket-Protocol` handshake header rather than the URL query string.
+     * Throws when no access token is available.
+     */
+    buildAuthProtocols(): string[];
     private openConnection;
     private handleAuthClose;
     private handleNetworkClose;
@@ -301,6 +342,7 @@ interface EmailSendOptions {
     to: string;
     context: Record<string, string | number | boolean>;
     userId?: string;
+    idempotencyKey?: string;
 }
 interface EmailSendResult {
     success: boolean;
@@ -678,17 +720,22 @@ interface ListMembershipsParams {
     cursor?: string;
 }
 interface SupportActor {
-    type: string;
+    type: SupportActorType;
     id?: string | null;
 }
+type SupportActorType = 'user' | 'practitioner' | 'anonymous' | 'service' | 'support_operator';
+type SupportCaseStatus = 'open' | 'in_progress' | 'resolved' | 'ignored';
+type SupportCasePriority = 'low' | 'normal' | 'high' | 'urgent';
+type SupportEventSeverity = 'info' | 'warning' | 'error' | 'critical';
+type SupportSourceChannel = 'issue_log' | 'support_thread' | 'email' | 'frontend' | 'api' | 'webhook';
 interface SupportCaseSummary {
     id: string;
     application_id: string;
     external_case_ref?: string | null;
     title?: string | null;
-    status: string;
-    priority: string;
-    highest_severity: string;
+    status: SupportCaseStatus;
+    priority: SupportCasePriority;
+    highest_severity: SupportEventSeverity;
     assigned_to_user_id?: string | null;
     first_event_at: string;
     last_event_at: string;
@@ -700,9 +747,9 @@ interface SupportCaseEvent {
     id: string;
     case_id: string;
     event_key: string;
-    source_channel: string;
+    source_channel: SupportSourceChannel;
     event_type: string;
-    severity: string;
+    severity: SupportEventSeverity;
     actor: SupportActor;
     correlation_id?: string | null;
     occurred_at: string;
@@ -712,9 +759,9 @@ interface SupportCaseEvent {
 interface SupportTelemetryIngestRequest {
     event_key: string;
     occurred_at: string;
-    source_channel: string;
+    source_channel: SupportSourceChannel;
     event_type: string;
-    severity: string;
+    severity: SupportEventSeverity;
     actor: SupportActor;
     payload: Record<string, unknown>;
     application_id?: string | null;
@@ -727,13 +774,13 @@ interface SupportTelemetryIngestResponse {
     case_id: string;
     created_case: boolean;
     deduplicated: boolean;
-    case_status: string;
+    case_status: SupportCaseStatus;
 }
 interface SupportTelemetryListCasesParams {
     application_id?: string;
-    status?: string;
-    priority?: string;
-    severity_gte?: string;
+    status?: SupportCaseStatus;
+    priority?: SupportCasePriority;
+    severity_gte?: SupportEventSeverity;
     assigned_to_user_id?: string;
     limit?: number;
     offset?: number;
@@ -748,16 +795,16 @@ interface SupportTelemetryCaseDetailResponse {
     event_total: number;
 }
 interface SupportTelemetryPatchCaseRequest {
-    status?: string;
-    priority?: string;
+    status?: SupportCaseStatus;
+    priority?: SupportCasePriority;
     assigned_to_user_id?: string | null;
     resolution_note?: string | null;
 }
 interface SupportTelemetryPatchCaseResponse {
     case: {
         id: string;
-        status: string;
-        priority: string;
+        status: SupportCaseStatus;
+        priority: SupportCasePriority;
         assigned_to_user_id?: string | null;
         resolved_at?: string | null;
         updated_at: string;
@@ -768,8 +815,8 @@ interface SupportTelemetryCaseByExternalResponse {
         id: string;
         application_id: string;
         external_case_ref?: string | null;
-        status: string;
-        priority: string;
+        status: SupportCaseStatus;
+        priority: SupportCasePriority;
         assigned_to_user_id?: string | null;
         resolved_at?: string | null;
         updated_at: string;
@@ -1390,9 +1437,21 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
     private normalizeAuthPayload;
     private storeAuthTokens;
     private unwrapAuthMethodResponse;
+    /**
+     * Unwrap the SPAPS `{ success, data }` response envelope for the legacy
+     * token-issuing auth methods (login/register/walletSignIn/refresh).
+     *
+     * The server's ResponseEnvelopeMiddleware wraps these responses, so the real
+     * tokens live at `response.data.data`. Reading `response.data.access_token`
+     * (one level too shallow) silently dropped the tokens. Reuse the shared
+     * `unwrapApiResponse` primitive so envelope handling and error fidelity stay
+     * consistent with the rest of the client.
+     */
+    private extractAuthResponse;
     private static isSdkManagedHeader;
     private static hasHeader;
     private static setHeader;
+    private static deleteHeader;
     private static assertSafeHeaderValue;
     private applyCustomHeaders;
     admin: {
@@ -1745,7 +1804,7 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
         register: (payload: {
             email: string;
             password: string;
-        }) => Promise<any>;
+        }) => Promise<AuthMethodResponse>;
         /**
          * Verify a magic link token and authenticate the user.
          * Returns full auth response with tokens and auto-stores them.
@@ -2282,4 +2341,4 @@ declare function createServerClient(secretKey: string, options?: Omit<SPAPSConfi
  */
 declare function detectKeyType(key: string): ApiKeyType | null;
 
-export { type AccessDecisionRequest, type AccessDecisionResponse, type AccountDeletionResponse, type ActionPreparationRequest, type ActionPreparationResponse, type AdminConfig, type ApiKeyType, type AuthDiscoveryMethod, type AuthMethodDescriptor, type AuthMethodResponse, type AuthMethodsResponse, type BatchEmailsResponse, type BatchUsersResponse, type CapabilityActionEnvironment, type CapabilityControlHints, type CapabilityDecisionActor, type CapabilityDecisionFact, type CapabilityDecisionNextAction, type CapabilityDecisionOutcome, type CapabilityDecisionReason, type CapabilityDecisionResource, type CapabilityDecisionSource, type CapabilityGraphContractResponse, type CapabilityGraphImpactQuery, type CapabilityGraphImpactResponse, type CapabilityGraphNode, type CapabilityGraphNodesQuery, type CapabilityGraphNodesResponse, type CapabilityGraphPath, type CapabilityGraphPathsQuery, type CapabilityGraphPathsResponse, type CapabilityGraphProjectionStatus, type CapabilityGraphRefreshDiagnostics, type CapabilityGraphRefreshPhase2Gate, type CapabilityGraphRefreshResponse, type CapabilityGraphRefreshSourceTiming, type CapabilityGraphRowStatus, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, type CreateSkillEvalCaseRequest, type CreateSkillEvalGovernanceSnapshotRequest, type CurrentUserProjectAccessParams, type CurrentUserProjectGrantListParams, DEFAULT_ADMIN_ACCOUNTS, type EmailSendOptions, type EmailSendResult, type EmailTemplate, type EmailTemplatePreview, type EntitlementCheckResult, type EntitlementListParams, type FeatureContext, type FeatureDefinition, FeatureEvaluator, type GraphExplainResponse, type HeaderProvider, ISSUE_REPORT_ATTACHMENT_ALLOWED_MIME_TYPES, ISSUE_REPORT_ATTACHMENT_MAX_BYTES, ISSUE_REPORT_ATTACHMENT_MAX_RETAINED, type ImportSkillEvalGovernanceOutcomeRequest, type IssueReportAttachmentMimeType, type IssueReportAttachmentUploadOptions, type IssueReportListParams, type IssueReportStatusParams, type ListMembershipsParams, type ListMembershipsResponse, type MarketingEventIngestRequest, type MarketingEventIngestResponse, type MarketingEventType, type MarketingExperimentDecision, type MarketingExperimentEffectDecision, type MarketingExperimentMinSampleDecision, type MarketingExperimentRecommendation, type MarketingExperimentResultsResponse, type MarketingExperimentSrmDecision, type MarketingExperimentSrmStatus, type MarketingExperimentVariantResult, type Membership, type MembershipInvitation, type MembershipMutationRequest, type MembershipMutationResponse, type MembershipRemoveResponse, type MembershipStatus, type MfaRequiredAuthResponse, type MfaTotpActivateRequest, type MfaTotpActivateResponse, type MfaTotpDisableRequest, type MfaTotpDisableResponse, type MfaTotpEnrollResponse, type MfaVerifyRequest, type MfaVerifyResponse, type OidcNonceResponse, type OidcSignInRequest, type PermissionCheckResult, PermissionChecker, type PersistedDecisionTrace, type PersistedDecisionTraceStep, type PreparedCapabilityActionStatus, type PreparedCapabilityExecution, type PreparedCapabilityNextAction, type PreparedCapabilitySideEffect, type RespondToSkillEvalReviewRequest, type RevealSkillEvalEvidenceRequest, RoleHierarchy, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type SPAPSEnvelope, type SPAPSErrorDiagnostic, type SPAPSErrorRemediation, SPAPSSDKError, type SPAPSSDKErrorOptions, type SessionContext, type SkillEvalAccessMode, type SkillEvalActorAccess, type SkillEvalCandidateInput, type SkillEvalCandidateResponse, type SkillEvalCasePolicy, type SkillEvalCaseResponse, type SkillEvalConfidence, type SkillEvalCreateOptions, type SkillEvalDisclosurePolicy, type SkillEvalEligibilitySource, type SkillEvalGovernanceOutcomeResult, type SkillEvalGovernancePurpose, type SkillEvalGovernanceSnapshotResult, type SkillEvalInsight, type SkillEvalInsightsResponse, type SkillEvalModelEffort, type SkillEvalMutationOptions, type SkillEvalPosterResponse, type SkillEvalPosterResponseResult, type SkillEvalRevealField, type SkillEvalRevealResult, type SkillEvalReviewMarkInput, type SkillEvalReviewMarkKind, type SkillEvalReviewResponse, type SkillEvalReviewRoom, type SkillEvalReviewerEligibilityInput, type SkillEvalRewardEvent, type SmsOtpRequest, type SmsOtpRequestResponse, type SmsOtpVerifyRequest, type SubmitSkillEvalReviewRequest, type SupportActor, type SupportCaseEvent, type SupportCaseSummary, type SupportTelemetryCaseByExternalResponse, type SupportTelemetryCaseDetailResponse, type SupportTelemetryIngestRequest, type SupportTelemetryIngestResponse, type SupportTelemetryListCasesParams, type SupportTelemetryListCasesResponse, type SupportTelemetryPatchCaseRequest, type SupportTelemetryPatchCaseResponse, type TemplateVariable, TokenManager, type UserBatchInfo, WalletUtils, type WebAuthnAssertionOptionsRequest, type WebAuthnAssertionVerifyRequest, type WebAuthnOptionsResponse, type WebAuthnRegisterVerifyRequest, type WebAuthnRegisterVerifyResponse, WebSocketAuthHelper, type WebSocketAuthHelperConfig, type WhitelistAddRequest, type WhitelistBulkAddRequest, type WhitelistBulkAddResponse, type WhitelistBulkEntry, type WhitelistBulkFailedEntry, type WhitelistCheckResponse, type WhitelistEntry, type WhitelistListParams, type WhitelistListResponse, type WhitelistMutationResponse, type WhitelistStatsResponse, type WhitelistUpdateRequest, type X402ExecuteActionOptions, X402PaymentRequiredSDKError, type X402ReceiptListParams, type X402VerifyHandoffOptions, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, isEnvelope, isErrorEnvelope, isSuccessEnvelope, unwrapEnvelope, unwrapNestedData, verifyCryptoWebhookSignature };
+export { type AccessDecisionRequest, type AccessDecisionResponse, type AccountDeletionResponse, type ActionPreparationRequest, type ActionPreparationResponse, type AdminConfig, type ApiKeyType, type AuthDiscoveryMethod, type AuthMethodDescriptor, type AuthMethodResponse, type AuthMethodsResponse, type BatchEmailsResponse, type BatchUsersResponse, type CapabilityActionEnvironment, type CapabilityControlHints, type CapabilityDecisionActor, type CapabilityDecisionFact, type CapabilityDecisionNextAction, type CapabilityDecisionOutcome, type CapabilityDecisionReason, type CapabilityDecisionResource, type CapabilityDecisionSource, type CapabilityGraphContractResponse, type CapabilityGraphImpactQuery, type CapabilityGraphImpactResponse, type CapabilityGraphNode, type CapabilityGraphNodesQuery, type CapabilityGraphNodesResponse, type CapabilityGraphPath, type CapabilityGraphPathsQuery, type CapabilityGraphPathsResponse, type CapabilityGraphProjectionStatus, type CapabilityGraphRefreshDiagnostics, type CapabilityGraphRefreshPhase2Gate, type CapabilityGraphRefreshResponse, type CapabilityGraphRefreshSourceTiming, type CapabilityGraphRowStatus, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, type CreateSkillEvalCaseRequest, type CreateSkillEvalGovernanceSnapshotRequest, type CurrentUserProjectAccessParams, type CurrentUserProjectGrantListParams, DEFAULT_ADMIN_ACCOUNTS, type EmailSendOptions, type EmailSendResult, type EmailTemplate, type EmailTemplatePreview, type EntitlementCheckResult, type EntitlementListParams, type FeatureContext, type FeatureDefinition, FeatureEvaluator, type GraphExplainResponse, type HeaderProvider, ISSUE_REPORT_ATTACHMENT_ALLOWED_MIME_TYPES, ISSUE_REPORT_ATTACHMENT_MAX_BYTES, ISSUE_REPORT_ATTACHMENT_MAX_RETAINED, type ImportSkillEvalGovernanceOutcomeRequest, type IssueReportAttachmentMimeType, type IssueReportAttachmentUploadOptions, type IssueReportListParams, type IssueReportStatusParams, type ListMembershipsParams, type ListMembershipsResponse, type MarketingEventIngestRequest, type MarketingEventIngestResponse, type MarketingEventType, type MarketingExperimentDecision, type MarketingExperimentEffectDecision, type MarketingExperimentMinSampleDecision, type MarketingExperimentRecommendation, type MarketingExperimentResultsResponse, type MarketingExperimentSrmDecision, type MarketingExperimentSrmStatus, type MarketingExperimentVariantResult, type Membership, type MembershipInvitation, type MembershipMutationRequest, type MembershipMutationResponse, type MembershipRemoveResponse, type MembershipStatus, type MfaRequiredAuthResponse, type MfaTotpActivateRequest, type MfaTotpActivateResponse, type MfaTotpDisableRequest, type MfaTotpDisableResponse, type MfaTotpEnrollResponse, type MfaVerifyRequest, type MfaVerifyResponse, type OidcNonceResponse, type OidcSignInRequest, type PermissionCheckResult, PermissionChecker, type PersistedDecisionTrace, type PersistedDecisionTraceStep, type PreparedCapabilityActionStatus, type PreparedCapabilityExecution, type PreparedCapabilityNextAction, type PreparedCapabilitySideEffect, type RespondToSkillEvalReviewRequest, type RevealSkillEvalEvidenceRequest, RoleHierarchy, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type SPAPSEnvelope, type SPAPSErrorDiagnostic, type SPAPSErrorRemediation, SPAPSSDKError, type SPAPSSDKErrorOptions, type SessionContext, type SkillEvalAccessMode, type SkillEvalActorAccess, type SkillEvalCandidateInput, type SkillEvalCandidateResponse, type SkillEvalCasePolicy, type SkillEvalCaseResponse, type SkillEvalConfidence, type SkillEvalCreateOptions, type SkillEvalDisclosurePolicy, type SkillEvalEligibilitySource, type SkillEvalGovernanceOutcomeResult, type SkillEvalGovernancePurpose, type SkillEvalGovernanceSnapshotResult, type SkillEvalInsight, type SkillEvalInsightsResponse, type SkillEvalModelEffort, type SkillEvalMutationOptions, type SkillEvalPosterResponse, type SkillEvalPosterResponseResult, type SkillEvalRevealField, type SkillEvalRevealResult, type SkillEvalReviewMarkInput, type SkillEvalReviewMarkKind, type SkillEvalReviewResponse, type SkillEvalReviewRoom, type SkillEvalReviewerEligibilityInput, type SkillEvalRewardEvent, type SmsOtpRequest, type SmsOtpRequestResponse, type SmsOtpVerifyRequest, type SubmitSkillEvalReviewRequest, type SupportActor, type SupportActorType, type SupportCaseEvent, type SupportCasePriority, type SupportCaseStatus, type SupportCaseSummary, type SupportEventSeverity, type SupportSourceChannel, type SupportTelemetryCaseByExternalResponse, type SupportTelemetryCaseDetailResponse, type SupportTelemetryIngestRequest, type SupportTelemetryIngestResponse, type SupportTelemetryListCasesParams, type SupportTelemetryListCasesResponse, type SupportTelemetryPatchCaseRequest, type SupportTelemetryPatchCaseResponse, type TemplateVariable, TokenManager, type UserBatchInfo, WalletUtils, type WebAuthnAssertionOptionsRequest, type WebAuthnAssertionVerifyRequest, type WebAuthnOptionsResponse, type WebAuthnRegisterVerifyRequest, type WebAuthnRegisterVerifyResponse, WebSocketAuthHelper, type WebSocketAuthHelperConfig, type WhitelistAddRequest, type WhitelistBulkAddRequest, type WhitelistBulkAddResponse, type WhitelistBulkEntry, type WhitelistBulkFailedEntry, type WhitelistCheckResponse, type WhitelistEntry, type WhitelistListParams, type WhitelistListResponse, type WhitelistMutationResponse, type WhitelistStatsResponse, type WhitelistUpdateRequest, type X402ExecuteActionOptions, X402PaymentRequiredSDKError, type X402ReceiptListParams, type X402VerifyHandoffOptions, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, isEnvelope, isErrorEnvelope, isSuccessEnvelope, unwrapEnvelope, unwrapNestedData, verifyCryptoWebhookSignature };

package/dist/index.js

@@ -335,6 +335,7 @@ var FeatureEvaluator = class {
 
 // src/websocket-auth-helper.ts
 var AUTH_CLOSE_CODES = /* @__PURE__ */ new Set([4001, 4003]);
+var WS_BEARER_SUBPROTOCOL = "spaps.bearer.v1";
 var WebSocketAuthHelper = class {
   config;
   ws = null;
@@ -348,6 +349,8 @@ var WebSocketAuthHelper = class {
       url: config.url,
       getAccessToken: config.getAccessToken,
       refreshAccessToken: config.refreshAccessToken,
+      getConnectTicket: config.getConnectTicket,
+      connectTimeoutMs: config.connectTimeoutMs ?? 1e4,
       refreshBufferSeconds: config.refreshBufferSeconds ?? 30,
       maxAuthRetries: config.maxAuthRetries ?? 3,
       maxNetworkRetries: config.maxNetworkRetries ?? 5,
@@ -363,7 +366,11 @@ var WebSocketAuthHelper = class {
   // ── Public API ──────────────────────────────────────────────────────────
   /**
    * Open an authenticated WebSocket connection.
-   * Appends the access token as a query parameter.
+   *
+   * The long-lived access token is never placed in the URL. Authentication uses
+   * a short-lived single-use connect ticket (`?ticket=...`) when
+   * `getConnectTicket` is configured, otherwise the bearer token is carried in
+   * the WebSocket subprotocol (handshake header).
    */
   async connect() {
     this.intentionalClose = false;
@@ -393,30 +400,84 @@ var WebSocketAuthHelper = class {
     this.ws.send(data);
   }
   // ── Internal helpers ────────────────────────────────────────────────────
-  /** Build the authenticated WebSocket URL. */
-  buildAuthUrl() {
+  /**
+   * Build the WebSocket URL.
+   *
+   * Never embeds the long-lived access token. When a short-lived connect
+   * `ticket` is supplied it is appended as `?ticket=<ticket>` (single-use,
+   * seconds-long TTL — inert if leaked). Otherwise the bare base URL is
+   * returned and the credential travels in the subprotocol instead.
+   */
+  buildAuthUrl(ticket) {
+    if (ticket) {
+      const separator = this.config.url.includes("?") ? "&" : "?";
+      return `${this.config.url}${separator}ticket=${encodeURIComponent(ticket)}`;
+    }
+    return this.config.url;
+  }
+  /**
+   * Build the WebSocket subprotocols carrying the bearer credential.
+   *
+   * Used only by the no-ticket fallback so the long-lived JWT travels in the
+   * `Sec-WebSocket-Protocol` handshake header rather than the URL query string.
+   * Throws when no access token is available.
+   */
+  buildAuthProtocols() {
     const token = this.config.getAccessToken();
     if (!token) {
       throw new Error("No access token available for WebSocket authentication");
     }
-    const separator = this.config.url.includes("?") ? "&" : "?";
-    return `${this.config.url}${separator}token=${encodeURIComponent(token)}`;
+    return [WS_BEARER_SUBPROTOCOL, token];
   }
   async openConnection() {
-    const url = this.buildAuthUrl();
+    let url;
+    let protocols;
+    if (this.config.getConnectTicket) {
+      const ticket = await this.config.getConnectTicket();
+      if (!ticket) {
+        throw new Error("Failed to obtain WebSocket connect ticket");
+      }
+      url = this.buildAuthUrl(ticket);
+      protocols = void 0;
+    } else {
+      url = this.buildAuthUrl();
+      protocols = this.buildAuthProtocols();
+    }
     return new Promise((resolve, reject) => {
+      let settled = false;
+      let connectTimer = null;
+      const settle = (action) => {
+        if (settled) return;
+        settled = true;
+        if (connectTimer) {
+          clearTimeout(connectTimer);
+          connectTimer = null;
+        }
+        action();
+      };
       try {
-        this.ws = new WebSocket(url);
+        this.ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url);
       } catch (err) {
-        reject(err);
+        settle(() => reject(err));
         return;
       }
+      if (this.config.connectTimeoutMs > 0) {
+        connectTimer = setTimeout(() => {
+          settle(() => {
+            try {
+              this.ws?.close();
+            } catch {
+            }
+            reject(new Error("WebSocket connection timed out before opening"));
+          });
+        }, this.config.connectTimeoutMs);
+      }
       this.ws.onopen = () => {
         this.networkRetries = 0;
         this.startPing();
         this.scheduleTokenRefresh();
         this.config.onOpen?.();
-        resolve();
+        settle(resolve);
       };
       this.ws.onmessage = (event) => {
         this.config.onMessage?.(String(event.data));
@@ -427,6 +488,13 @@ var WebSocketAuthHelper = class {
       this.ws.onclose = (event) => {
         this.cleanup();
         this.config.onClose?.(event.code, event.reason);
+        settle(
+          () => reject(
+            new Error(
+              `WebSocket closed before opening (code ${event.code}${event.reason ? `: ${event.reason}` : ""})`
+            )
+          )
+        );
         if (this.intentionalClose) {
           return;
         }
@@ -817,6 +885,22 @@ var SPAPSClient = class _SPAPSClient {
     this.storeAuthTokens(result);
     return result;
   }
+  /**
+   * Unwrap the SPAPS `{ success, data }` response envelope for the legacy
+   * token-issuing auth methods (login/register/walletSignIn/refresh).
+   *
+   * The server's ResponseEnvelopeMiddleware wraps these responses, so the real
+   * tokens live at `response.data.data`. Reading `response.data.access_token`
+   * (one level too shallow) silently dropped the tokens. Reuse the shared
+   * `unwrapApiResponse` primitive so envelope handling and error fidelity stay
+   * consistent with the rest of the client.
+   */
+  extractAuthResponse(response, fallback) {
+    return this.unwrapApiResponse(
+      response,
+      fallback
+    );
+  }
   static isSdkManagedHeader(name) {
     const normalized = name.toLowerCase();
     return normalized === "authorization" || normalized === "x-api-key";
@@ -836,6 +920,19 @@ var SPAPSClient = class _SPAPSClient {
     }
     headers[name] = value;
   }
+  static deleteHeader(headers, name) {
+    if (!headers) return;
+    if (typeof headers.delete === "function") {
+      headers.delete(name);
+      return;
+    }
+    const normalized = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === normalized) {
+        delete headers[key];
+      }
+    }
+  }
   static assertSafeHeaderValue(name, value) {
     if (typeof value === "string" && /[\r\n]/.test(value)) {
       throw new Error(`Invalid header value for ${name}: control characters not allowed`);
@@ -1049,10 +1146,14 @@ var SPAPSClient = class _SPAPSClient {
       } else {
         formData.append("file", file);
       }
+      const uploadHeaders = { "Content-Type": null };
+      if (this.accessToken) {
+        uploadHeaders.Authorization = `Bearer ${this.accessToken}`;
+      }
       const res = await this.client.post(
         "/api/v1/issue-reports/attachments",
         formData,
-        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+        { headers: uploadHeaders }
       );
       return this.unwrapApiResponse(res, "Failed to upload issue report attachment");
     },
@@ -1535,6 +1636,9 @@ var SPAPSClient = class _SPAPSClient {
     });
     this.client.interceptors.request.use((config2) => {
       config2.headers = config2.headers || {};
+      if (typeof FormData !== "undefined" && config2.data instanceof FormData) {
+        _SPAPSClient.deleteHeader(config2.headers, "Content-Type");
+      }
       this.applyCustomHeaders(config2.headers);
       if (this.apiKey && !_SPAPSClient.hasHeader(config2.headers, "X-API-Key")) {
         _SPAPSClient.setHeader(config2.headers, "X-API-Key", this.apiKey);
@@ -1547,15 +1651,18 @@ var SPAPSClient = class _SPAPSClient {
     this.client.interceptors.response.use(
       (response) => response,
       async (error) => {
-        if (error.response?.status === 401 && this.refreshToken) {
+        const cfg = error.config || {};
+        const requestUrl = cfg.url || "";
+        const shouldAttemptRefresh = error.response?.status === 401 && !!this.refreshToken && !cfg.__isRetry && !requestUrl.includes("/api/auth/refresh") && !!error.config;
+        if (shouldAttemptRefresh) {
           try {
             const { data } = await this.refresh(this.refreshToken);
             this.accessToken = data.access_token;
             this.refreshToken = data.refresh_token;
-            if (error.config) {
-              error.config.headers.Authorization = `Bearer ${this.accessToken}`;
-              return this.client.request(error.config);
-            }
+            cfg.__isRetry = true;
+            cfg.headers = cfg.headers || {};
+            _SPAPSClient.setHeader(cfg.headers, "Authorization", `Bearer ${this.accessToken}`);
+            return this.client.request(cfg);
           } catch (refreshError) {
             this.accessToken = void 0;
             this.refreshToken = void 0;
@@ -1598,18 +1705,21 @@ var SPAPSClient = class _SPAPSClient {
       email,
       password
     });
-    this.accessToken = response.data.access_token;
-    this.refreshToken = response.data.refresh_token;
-    return response;
+    const data = this.extractAuthResponse(response, "Login failed");
+    this.accessToken = data.access_token;
+    this.refreshToken = data.refresh_token;
+    return { data };
   }
   async register(email, password) {
     const response = await this.client.post("/api/auth/register", {
       email,
       password
     });
-    this.accessToken = response.data.access_token;
-    this.refreshToken = response.data.refresh_token;
-    return response;
+    const data = this.normalizeAuthPayload(
+      this.extractAuthResponse(response, "Registration failed")
+    );
+    this.storeAuthTokens(data);
+    return { data };
   }
   async walletSignIn(walletAddress, signature, message, chainType = "solana") {
     const response = await this.client.post("/api/auth/wallet-sign-in", {
@@ -1618,17 +1728,19 @@ var SPAPSClient = class _SPAPSClient {
       message,
       chain_type: chainType
     });
-    this.accessToken = response.data.access_token;
-    this.refreshToken = response.data.refresh_token;
-    return response;
+    const data = this.extractAuthResponse(response, "Wallet sign-in failed");
+    this.accessToken = data.access_token;
+    this.refreshToken = data.refresh_token;
+    return { data };
   }
   async refresh(refreshToken) {
     const response = await this.client.post("/api/auth/refresh", {
       refresh_token: refreshToken || this.refreshToken
     });
-    this.accessToken = response.data.access_token;
-    this.refreshToken = response.data.refresh_token;
-    return response;
+    const data = this.extractAuthResponse(response, "Token refresh failed");
+    this.accessToken = data.access_token;
+    this.refreshToken = data.refresh_token;
+    return { data };
   }
   async logout() {
     await this.client.post("/api/auth/logout");
@@ -1636,7 +1748,9 @@ var SPAPSClient = class _SPAPSClient {
     this.refreshToken = void 0;
   }
   async getUser() {
-    return this.client.get("/api/auth/user");
+    const res = await this.client.get("/api/auth/user");
+    const payload = this.unwrapApiResponse(res, "Failed to get user");
+    return { data: payload.user };
   }
   async getSessionContext() {
     const res = await this.client.get("/api/auth/session-context", this.authConfig());
@@ -1715,12 +1829,7 @@ var SPAPSClient = class _SPAPSClient {
     },
     register: async (payload) => {
       const res = await this.client.post("/api/auth/register", payload);
-      const body = res.data;
-      if (body?.success === false) throw new Error(body?.error?.message || "Register failed");
-      const data = body?.data ?? body;
-      this.accessToken = data.access_token;
-      this.refreshToken = data.refresh_token;
-      return data;
+      return this.unwrapAuthMethodResponse(res, "Register failed");
     },
     /**
      * Verify a magic link token and authenticate the user.
@@ -2522,15 +2631,25 @@ var SPAPSClient = class _SPAPSClient {
   }
   async getSubscription(subscriptionId) {
     if (subscriptionId) {
-      return this.client.get(`/api/stripe/subscription/${subscriptionId}`);
+      const res = await this.client.get(
+        `/api/stripe/subscription/${subscriptionId}`
+      );
+      return { data: this.unwrapApiResponse(res, "Failed to get subscription") };
     }
-    return this.client.get("/api/stripe/subscriptions");
+    const response = await this.client.get(
+      "/api/stripe/subscriptions"
+    );
+    return { data: response.data?.subscriptions ?? [] };
   }
   async cancelSubscription(subscriptionId, options = {}) {
     if (!subscriptionId) {
       throw new Error("subscriptionId is required to cancel a subscription.");
     }
-    return this.client.post(`/api/stripe/subscription/${subscriptionId}/cancel`, options);
+    const res = await this.client.post(
+      `/api/stripe/subscription/${subscriptionId}/cancel`,
+      options
+    );
+    return { data: this.unwrapApiResponse(res, "Failed to cancel subscription") };
   }
   // Usage Methods
   async authorizeUsage(payload) {
@@ -2573,7 +2692,8 @@ var SPAPSClient = class _SPAPSClient {
       template_key: options.templateKey,
       to: options.to,
       context: options.context,
-      ...options.userId && { user_id: options.userId }
+      ...options.userId && { user_id: options.userId },
+      ...options.idempotencyKey && { idempotency_key: options.idempotencyKey }
     });
     return this.unwrapApiResponse(response, "Failed to send email");
   }

package/dist/index.mjs

@@ -296,6 +296,7 @@ var FeatureEvaluator = class {
 
 // src/websocket-auth-helper.ts
 var AUTH_CLOSE_CODES = /* @__PURE__ */ new Set([4001, 4003]);
+var WS_BEARER_SUBPROTOCOL = "spaps.bearer.v1";
 var WebSocketAuthHelper = class {
   config;
   ws = null;
@@ -309,6 +310,8 @@ var WebSocketAuthHelper = class {
       url: config.url,
       getAccessToken: config.getAccessToken,
       refreshAccessToken: config.refreshAccessToken,
+      getConnectTicket: config.getConnectTicket,
+      connectTimeoutMs: config.connectTimeoutMs ?? 1e4,
       refreshBufferSeconds: config.refreshBufferSeconds ?? 30,
       maxAuthRetries: config.maxAuthRetries ?? 3,
       maxNetworkRetries: config.maxNetworkRetries ?? 5,
@@ -324,7 +327,11 @@ var WebSocketAuthHelper = class {
   // ── Public API ──────────────────────────────────────────────────────────
   /**
    * Open an authenticated WebSocket connection.
-   * Appends the access token as a query parameter.
+   *
+   * The long-lived access token is never placed in the URL. Authentication uses
+   * a short-lived single-use connect ticket (`?ticket=...`) when
+   * `getConnectTicket` is configured, otherwise the bearer token is carried in
+   * the WebSocket subprotocol (handshake header).
    */
   async connect() {
     this.intentionalClose = false;
@@ -354,30 +361,84 @@ var WebSocketAuthHelper = class {
     this.ws.send(data);
   }
   // ── Internal helpers ────────────────────────────────────────────────────
-  /** Build the authenticated WebSocket URL. */
-  buildAuthUrl() {
+  /**
+   * Build the WebSocket URL.
+   *
+   * Never embeds the long-lived access token. When a short-lived connect
+   * `ticket` is supplied it is appended as `?ticket=<ticket>` (single-use,
+   * seconds-long TTL — inert if leaked). Otherwise the bare base URL is
+   * returned and the credential travels in the subprotocol instead.
+   */
+  buildAuthUrl(ticket) {
+    if (ticket) {
+      const separator = this.config.url.includes("?") ? "&" : "?";
+      return `${this.config.url}${separator}ticket=${encodeURIComponent(ticket)}`;
+    }
+    return this.config.url;
+  }
+  /**
+   * Build the WebSocket subprotocols carrying the bearer credential.
+   *
+   * Used only by the no-ticket fallback so the long-lived JWT travels in the
+   * `Sec-WebSocket-Protocol` handshake header rather than the URL query string.
+   * Throws when no access token is available.
+   */
+  buildAuthProtocols() {
     const token = this.config.getAccessToken();
     if (!token) {
       throw new Error("No access token available for WebSocket authentication");
     }
-    const separator = this.config.url.includes("?") ? "&" : "?";
-    return `${this.config.url}${separator}token=${encodeURIComponent(token)}`;
+    return [WS_BEARER_SUBPROTOCOL, token];
   }
   async openConnection() {
-    const url = this.buildAuthUrl();
+    let url;
+    let protocols;
+    if (this.config.getConnectTicket) {
+      const ticket = await this.config.getConnectTicket();
+      if (!ticket) {
+        throw new Error("Failed to obtain WebSocket connect ticket");
+      }
+      url = this.buildAuthUrl(ticket);
+      protocols = void 0;
+    } else {
+      url = this.buildAuthUrl();
+      protocols = this.buildAuthProtocols();
+    }
     return new Promise((resolve, reject) => {
+      let settled = false;
+      let connectTimer = null;
+      const settle = (action) => {
+        if (settled) return;
+        settled = true;
+        if (connectTimer) {
+          clearTimeout(connectTimer);
+          connectTimer = null;
+        }
+        action();
+      };
       try {
-        this.ws = new WebSocket(url);
+        this.ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url);
       } catch (err) {
-        reject(err);
+        settle(() => reject(err));
         return;
       }
+      if (this.config.connectTimeoutMs > 0) {
+        connectTimer = setTimeout(() => {
+          settle(() => {
+            try {
+              this.ws?.close();
+            } catch {
+            }
+            reject(new Error("WebSocket connection timed out before opening"));
+          });
+        }, this.config.connectTimeoutMs);
+      }
       this.ws.onopen = () => {
         this.networkRetries = 0;
         this.startPing();
         this.scheduleTokenRefresh();
         this.config.onOpen?.();
-        resolve();
+        settle(resolve);
       };
       this.ws.onmessage = (event) => {
         this.config.onMessage?.(String(event.data));
@@ -388,6 +449,13 @@ var WebSocketAuthHelper = class {
       this.ws.onclose = (event) => {
         this.cleanup();
         this.config.onClose?.(event.code, event.reason);
+        settle(
+          () => reject(
+            new Error(
+              `WebSocket closed before opening (code ${event.code}${event.reason ? `: ${event.reason}` : ""})`
+            )
+          )
+        );
         if (this.intentionalClose) {
           return;
         }
@@ -778,6 +846,22 @@ var SPAPSClient = class _SPAPSClient {
     this.storeAuthTokens(result);
     return result;
   }
+  /**
+   * Unwrap the SPAPS `{ success, data }` response envelope for the legacy
+   * token-issuing auth methods (login/register/walletSignIn/refresh).
+   *
+   * The server's ResponseEnvelopeMiddleware wraps these responses, so the real
+   * tokens live at `response.data.data`. Reading `response.data.access_token`
+   * (one level too shallow) silently dropped the tokens. Reuse the shared
+   * `unwrapApiResponse` primitive so envelope handling and error fidelity stay
+   * consistent with the rest of the client.
+   */
+  extractAuthResponse(response, fallback) {
+    return this.unwrapApiResponse(
+      response,
+      fallback
+    );
+  }
   static isSdkManagedHeader(name) {
     const normalized = name.toLowerCase();
     return normalized === "authorization" || normalized === "x-api-key";
@@ -797,6 +881,19 @@ var SPAPSClient = class _SPAPSClient {
     }
     headers[name] = value;
   }
+  static deleteHeader(headers, name) {
+    if (!headers) return;
+    if (typeof headers.delete === "function") {
+      headers.delete(name);
+      return;
+    }
+    const normalized = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === normalized) {
+        delete headers[key];
+      }
+    }
+  }
   static assertSafeHeaderValue(name, value) {
     if (typeof value === "string" && /[\r\n]/.test(value)) {
       throw new Error(`Invalid header value for ${name}: control characters not allowed`);
@@ -1010,10 +1107,14 @@ var SPAPSClient = class _SPAPSClient {
       } else {
         formData.append("file", file);
       }
+      const uploadHeaders = { "Content-Type": null };
+      if (this.accessToken) {
+        uploadHeaders.Authorization = `Bearer ${this.accessToken}`;
+      }
       const res = await this.client.post(
         "/api/v1/issue-reports/attachments",
         formData,
-        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+        { headers: uploadHeaders }
       );
       return this.unwrapApiResponse(res, "Failed to upload issue report attachment");
     },
@@ -1496,6 +1597,9 @@ var SPAPSClient = class _SPAPSClient {
     });
     this.client.interceptors.request.use((config2) => {
       config2.headers = config2.headers || {};
+      if (typeof FormData !== "undefined" && config2.data instanceof FormData) {
+        _SPAPSClient.deleteHeader(config2.headers, "Content-Type");
+      }
       this.applyCustomHeaders(config2.headers);
       if (this.apiKey && !_SPAPSClient.hasHeader(config2.headers, "X-API-Key")) {
         _SPAPSClient.setHeader(config2.headers, "X-API-Key", this.apiKey);
@@ -1508,15 +1612,18 @@ var SPAPSClient = class _SPAPSClient {
     this.client.interceptors.response.use(
       (response) => response,
       async (error) => {
-        if (error.response?.status === 401 && this.refreshToken) {
+        const cfg = error.config || {};
+        const requestUrl = cfg.url || "";
+        const shouldAttemptRefresh = error.response?.status === 401 && !!this.refreshToken && !cfg.__isRetry && !requestUrl.includes("/api/auth/refresh") && !!error.config;
+        if (shouldAttemptRefresh) {
           try {
             const { data } = await this.refresh(this.refreshToken);
             this.accessToken = data.access_token;
             this.refreshToken = data.refresh_token;
-            if (error.config) {
-              error.config.headers.Authorization = `Bearer ${this.accessToken}`;
-              return this.client.request(error.config);
-            }
+            cfg.__isRetry = true;
+            cfg.headers = cfg.headers || {};
+            _SPAPSClient.setHeader(cfg.headers, "Authorization", `Bearer ${this.accessToken}`);
+            return this.client.request(cfg);
           } catch (refreshError) {
             this.accessToken = void 0;
             this.refreshToken = void 0;
@@ -1559,18 +1666,21 @@ var SPAPSClient = class _SPAPSClient {
       email,
       password
     });
-    this.accessToken = response.data.access_token;
-    this.refreshToken = response.data.refresh_token;
-    return response;
+    const data = this.extractAuthResponse(response, "Login failed");
+    this.accessToken = data.access_token;
+    this.refreshToken = data.refresh_token;
+    return { data };
   }
   async register(email, password) {
     const response = await this.client.post("/api/auth/register", {
       email,
       password
     });
-    this.accessToken = response.data.access_token;
-    this.refreshToken = response.data.refresh_token;
-    return response;
+    const data = this.normalizeAuthPayload(
+      this.extractAuthResponse(response, "Registration failed")
+    );
+    this.storeAuthTokens(data);
+    return { data };
   }
   async walletSignIn(walletAddress, signature, message, chainType = "solana") {
     const response = await this.client.post("/api/auth/wallet-sign-in", {
@@ -1579,17 +1689,19 @@ var SPAPSClient = class _SPAPSClient {
       message,
       chain_type: chainType
     });
-    this.accessToken = response.data.access_token;
-    this.refreshToken = response.data.refresh_token;
-    return response;
+    const data = this.extractAuthResponse(response, "Wallet sign-in failed");
+    this.accessToken = data.access_token;
+    this.refreshToken = data.refresh_token;
+    return { data };
   }
   async refresh(refreshToken) {
     const response = await this.client.post("/api/auth/refresh", {
       refresh_token: refreshToken || this.refreshToken
     });
-    this.accessToken = response.data.access_token;
-    this.refreshToken = response.data.refresh_token;
-    return response;
+    const data = this.extractAuthResponse(response, "Token refresh failed");
+    this.accessToken = data.access_token;
+    this.refreshToken = data.refresh_token;
+    return { data };
   }
   async logout() {
     await this.client.post("/api/auth/logout");
@@ -1597,7 +1709,9 @@ var SPAPSClient = class _SPAPSClient {
     this.refreshToken = void 0;
   }
   async getUser() {
-    return this.client.get("/api/auth/user");
+    const res = await this.client.get("/api/auth/user");
+    const payload = this.unwrapApiResponse(res, "Failed to get user");
+    return { data: payload.user };
   }
   async getSessionContext() {
     const res = await this.client.get("/api/auth/session-context", this.authConfig());
@@ -1676,12 +1790,7 @@ var SPAPSClient = class _SPAPSClient {
     },
     register: async (payload) => {
       const res = await this.client.post("/api/auth/register", payload);
-      const body = res.data;
-      if (body?.success === false) throw new Error(body?.error?.message || "Register failed");
-      const data = body?.data ?? body;
-      this.accessToken = data.access_token;
-      this.refreshToken = data.refresh_token;
-      return data;
+      return this.unwrapAuthMethodResponse(res, "Register failed");
     },
     /**
      * Verify a magic link token and authenticate the user.
@@ -2483,15 +2592,25 @@ var SPAPSClient = class _SPAPSClient {
   }
   async getSubscription(subscriptionId) {
     if (subscriptionId) {
-      return this.client.get(`/api/stripe/subscription/${subscriptionId}`);
+      const res = await this.client.get(
+        `/api/stripe/subscription/${subscriptionId}`
+      );
+      return { data: this.unwrapApiResponse(res, "Failed to get subscription") };
     }
-    return this.client.get("/api/stripe/subscriptions");
+    const response = await this.client.get(
+      "/api/stripe/subscriptions"
+    );
+    return { data: response.data?.subscriptions ?? [] };
   }
   async cancelSubscription(subscriptionId, options = {}) {
     if (!subscriptionId) {
       throw new Error("subscriptionId is required to cancel a subscription.");
     }
-    return this.client.post(`/api/stripe/subscription/${subscriptionId}/cancel`, options);
+    const res = await this.client.post(
+      `/api/stripe/subscription/${subscriptionId}/cancel`,
+      options
+    );
+    return { data: this.unwrapApiResponse(res, "Failed to cancel subscription") };
   }
   // Usage Methods
   async authorizeUsage(payload) {
@@ -2534,7 +2653,8 @@ var SPAPSClient = class _SPAPSClient {
       template_key: options.templateKey,
       to: options.to,
       context: options.context,
-      ...options.userId && { user_id: options.userId }
+      ...options.userId && { user_id: options.userId },
+      ...options.idempotencyKey && { idempotency_key: options.idempotencyKey }
     });
     return this.unwrapApiResponse(response, "Failed to send email");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps-sdk",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "description": "Sweet Potato Authentication & Payment Service SDK - Zero-config client with built-in permission checking, role-based access control, and dayrate scheduling",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -51,7 +51,7 @@
   "dependencies": {
     "axios": "^1.15.1",
     "cross-fetch": "^4.0.0",
-    "spaps-types": "^1.5.0"
+    "spaps-types": "^1.5.2"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
@@ -81,4 +81,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}