spaps-sdk 1.6.7 → 1.7.0

package/CHANGELOG.md

@@ -6,7 +6,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
-- No changes yet.
+- Added `dayrate.getCheckoutStatus(sessionId)` and checkout-status response types for Bookme/dayrate confirmation polling.
+- Added browser-safe runtime helpers: guarded environment reads, `TokenManager.decodePayload()`, and SPAPS envelope unwrapping/type guards.
+- Added `headerProvider` SDK config for per-request custom context headers without overriding SDK-managed auth headers.
+
+## [1.6.8] - 2026-04-25
+
+- Maintenance: align the published SDK package version after release automation.
+
+## [1.6.7] - 2026-04-25
+
+- Maintenance: align the published SDK package version after release automation.
 
 ## [1.6.6] - 2026-04-20
 

package/README.md

@@ -23,7 +23,7 @@ This package targets `Node.js >=14`.
 
 | Need | Package gives you |
 | --- | --- |
-| One client for many SPAPS surfaces | `auth`, `payments`, `sessions`, `secureMessages`, `issueReporting`, `email`, `entitlements`, `dayrate`, `admin`, and `cfo` namespaces |
+| One client for many SPAPS surfaces | `auth`, `payments`, `sessions`, `secureMessages`, `issueReporting`, `appLinks`, `email`, `entitlements`, `skillEvals`, `dayrate`, `admin`, and `cfo` namespaces |
 | Local development without extra config | Localhost URLs automatically enable local mode |
 | Browser and server usage | `publishableKey`, `secretKey`, or legacy `apiKey` support |
 | Shared contracts | Re-exports a large slice of `spaps-types` |
@@ -67,6 +67,7 @@ Constructor values take precedence over environment variables.
 | `secretKey` | Server-side key for privileged access |
 | `apiKey` | Legacy key field kept for compatibility |
 | `timeout` | Request timeout override |
+| `headerProvider` | Optional function returning custom headers to add to every SDK request without overriding `Authorization` or `X-API-Key` |
 
 Relevant environment variables:
 
@@ -84,9 +85,11 @@ Relevant environment variables:
 | `sessions` | Session lookup, validation, and lifecycle helpers |
 | `secureMessages` | Secure-message create/list helpers |
 | `issueReporting` | Status, history, create, update, reply, and voice-token flows |
+| `appLinks` | Authenticated create and public resolve helpers for application-scoped short links |
 | `email` | Template lookup, preview, and send helpers |
 | `entitlements` | User and resource entitlement queries |
-| `dayrate` | Availability and booking helpers |
+| `skillEvals` | Paid blind skill-eval cases, review rooms, controlled reveal, and governance snapshots |
+| `dayrate` | Availability, Stripe booking, x402 booking-hold, and checkout-status helpers |
 | `admin` | Product and pricing admin helpers |
 | `cfo` | CFO-facing reporting endpoints |
 
@@ -120,6 +123,86 @@ const voiceToken = await spaps.issueReporting.createVoiceToken();
 console.log(voiceToken.provider, voiceToken.model_id);
 ```
 
+### Application Short Links
+
+Use `appLinks` when a browser app needs a stable public URL for large local state, such as compressed diagram state.
+
+```ts
+const spaps = new SPAPSClient({
+  apiUrl: "https://api.example.test",
+  publishableKey: "spaps_pub_example",
+});
+spaps.setAccessToken(accessToken);
+
+const link = await spaps.appLinks.create({
+  app_slug: "mmdx",
+  resource_kind: "mermaid-diagram",
+  target_path: "/diagrams",
+  metadata: { diagram_state: "pako:..." },
+});
+
+console.log(`/${link.app_slug}/${link.username}/${link.slug}`);
+```
+
+### Skill Evals
+
+Use `skillEvals` for SPAPS-owned blind comparative review cases. Paid creation uses the same `PAYMENT-SIGNATURE` header shape as the x402 namespace.
+
+```ts
+const signedPayment = "base64-x402-payment";
+
+const created = await spaps.skillEvals.createCase(
+  {
+    title: "Docs skill comparison",
+    task_claim: "Compare both implementations.",
+    success_criteria: ["Finds repo boundaries"],
+    candidates: [
+      {
+        candidate_id: "A",
+        output_ref: "spaps-artifact://case/a",
+        evidence_summary: "Validation passed",
+        artifact_hash: "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        artifact_mime: "text/markdown",
+        skill_version_digest: "sha256:1111111111111111111111111111111111111111111111111111111111111111",
+        provenance_ref: "skill://private/a",
+      },
+      {
+        candidate_id: "B",
+        output_ref: "spaps-artifact://case/b",
+        evidence_summary: "Validation passed",
+        artifact_hash: "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        artifact_mime: "text/markdown",
+        skill_version_digest: "sha256:2222222222222222222222222222222222222222222222222222222222222222",
+        provenance_ref: "skill://private/b",
+      },
+    ],
+    idempotency_key: "eval-create-001",
+  },
+  { paymentSignature: signedPayment }
+);
+
+const room = await spaps.skillEvals.getReviewRoom(created.case_id);
+console.log(room.reviewer_state);
+```
+
+### Custom Context Headers
+
+Use `headerProvider` when an app needs to attach tenant, app, or principal context to SDK requests:
+
+```ts
+const spaps = new SPAPSClient({
+  apiUrl: "https://api.example.test",
+  publishableKey: "spaps_pub_example",
+  headerProvider: () => ({
+    "X-Tenant-Role": resolveTenantRole(),
+    "X-App-Slug": "unclawg",
+    "X-Principal-Id": resolvePrincipalId(),
+  }),
+});
+```
+
+The provider runs on each request. Headers named `Authorization` or `X-API-Key` are ignored because the SDK manages those from `setAccessToken()`, `publishableKey`, `secretKey`, or `apiKey`.
+
 ### Permission Helpers With Explicit Admin Config
 
 ```ts
@@ -142,6 +225,27 @@ const isAdmin = isAdminAccount("admin@example.com", customAdmins);
 console.log(role, adminCheck.allowed, isAdmin);
 ```
 
+### Runtime Helpers
+
+```ts
+import {
+  TokenManager,
+  isErrorEnvelope,
+  unwrapEnvelope,
+  unwrapNestedData,
+} from "spaps-sdk";
+
+const payload = TokenManager.decodePayload(accessToken);
+const response = unwrapEnvelope(await spaps.health());
+const items = unwrapNestedData(listResponse);
+
+if (isErrorEnvelope(errorBody)) {
+  console.error(errorBody.error.code, errorBody.error.message);
+}
+```
+
+`decodePayload()` returns `null` for invalid JWTs or non-object payloads. The envelope helpers accept unknown API payloads so apps can handle SPAPS success/error envelopes without copying ad hoc response guards.
+
 ### Convenience Helpers
 
 ```ts
@@ -215,7 +319,7 @@ npm run test:readme
 ## Metadata
 
 - `package_name`: `spaps-sdk`
-- `latest_version`: `1.6.6`
+- `latest_version`: `1.6.8`
 - `minimum_runtime`: `Node.js >=14.0.0`
 - `api_base_url`: `https://api.sweetpotato.dev`
 

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as spaps_types from 'spaps-types';
-import { ResourceType, Entitlement, CreateProductRequest, Product, UpdateProductRequest, CreatePriceRequest, Price, ProductSyncResult, CryptoReconcileRequest, CreateSecureMessageRequest, SecureMessage, IssueReportScope, IssueReportStatusResult, IssueReportStatus, IssueReportListResult, IssueReport, CreateIssueReportRequest, IssueReportingVoiceTokenResult, UpdateIssueReportRequest, ReplyIssueReportRequest, AuthResponse, User as User$1, CreateCryptoInvoiceRequest, CryptoInvoiceStatusSnapshot, CheckoutSession, DayrateAvailabilityResponse, DayrateBookingRequest, DayrateBookingResponse, DayrateMultiBookingRequest, DayrateMultiBookingResponse, Subscription, UsageBalance, VerifyCryptoWebhookSignatureOptions } from 'spaps-types';
-export { AdminPermission, AdminRole, AdminUser, ApiResponse, AuthResponse, CheckoutSession, CreateCryptoInvoiceRequest, CreateIssueReportRequest, CreatePriceRequest, CreateProductRequest, CreateSecureMessageInput, CreateSecureMessageRequest, CryptoInvoice, CryptoInvoiceResponse, CryptoInvoiceStatusSnapshot, CryptoReconcileRequest, DayrateAvailabilityResponse, DayrateAvailableSlot, DayrateBookingRequest, DayrateBookingResponse, DayrateDayOfWeek, DayrateMultiBookingRequest, DayrateMultiBookingResponse, DayratePriceBreakdown, DayrateSlotType, Entitlement, IssueReport, IssueReportListResult, IssueReportStatus, IssueReportStatusResult, IssueReportTarget, IssueReportingInputMode, IssueReportingVoiceProvider, IssueReportingVoiceTokenResult, LinkedIssueReportCase, Price, Product, ProductSyncResult, ReplyIssueReportRequest, ResourceType, SecureMessage, SecureMessageOutput, Subscription, TokenPair, UpdateIssueReportRequest, UpdateProductRequest, UsageBalance, User, UserProfile, UserRole, UserWallet, VerifyCryptoWebhookSignatureOptions, createSecureMessageRequestSchema, secureMessageMetadataSchema, secureMessageSchema } from 'spaps-types';
+import { ResourceType, Entitlement, CreateProductRequest, Product, UpdateProductRequest, CreatePriceRequest, Price, ProductSyncResult, CryptoReconcileRequest, CreateSecureMessageRequest, SecureMessage, IssueReportScope, IssueReportStatusResult, IssueReportStatus, IssueReportListResult, IssueReport, CreateIssueReportRequest, IssueReportingVoiceTokenResult, UpdateIssueReportRequest, ReplyIssueReportRequest, CreateAppLinkRequest, AppLink, AuthResponse, User as User$1, CreateCryptoInvoiceRequest, CryptoInvoiceStatusSnapshot, CheckoutSession, X402ResourceStatusResponse, X402ActionResponse, X402ReceiptResponse, X402ReceiptListResponse, X402HandoffVerification, DayrateAvailabilityResponse, DayrateBookingRequest, DayrateBookingResponse, DayrateMultiBookingRequest, DayrateMultiBookingResponse, DayrateX402BookingRequest, DayrateX402BookingResponse, DayrateCheckoutStatusResponse, Subscription, UsageBalance, VerifyCryptoWebhookSignatureOptions } from 'spaps-types';
+export { AdminPermission, AdminRole, AdminUser, ApiResponse, AppLink, AuthResponse, CheckoutSession, CreateAppLinkRequest, CreateCryptoInvoiceRequest, CreateIssueReportRequest, CreatePriceRequest, CreateProductRequest, CreateSecureMessageInput, CreateSecureMessageRequest, CryptoInvoice, CryptoInvoiceResponse, CryptoInvoiceStatusSnapshot, CryptoReconcileRequest, DayrateAvailabilityResponse, DayrateAvailableSlot, DayrateBookingRequest, DayrateBookingResponse, DayrateCheckoutStatus, DayrateCheckoutStatusBooking, DayrateCheckoutStatusResponse, DayrateDayOfWeek, DayrateMultiBookingRequest, DayrateMultiBookingResponse, DayratePriceBreakdown, DayrateSlotType, DayrateX402BookingRequest, DayrateX402BookingResponse, Entitlement, IssueReport, IssueReportListResult, IssueReportStatus, IssueReportStatusResult, IssueReportTarget, IssueReportingInputMode, IssueReportingVoiceProvider, IssueReportingVoiceTokenResult, LinkedIssueReportCase, Price, Product, ProductSyncResult, ReplyIssueReportRequest, ResourceType, SecureMessage, SecureMessageOutput, Subscription, TokenPair, UpdateIssueReportRequest, UpdateProductRequest, UsageBalance, User, UserProfile, UserRole, UserWallet, VerifyCryptoWebhookSignatureOptions, X402ActionFreeResponse, X402ActionOutcome, X402ActionPendingResponse, X402ActionReplayedResponse, X402ActionResponse, X402ActionSettledResponse, X402ExecuteActionRequest, X402HandoffAuthorization, X402HandoffVerification, X402HandoffVerifyRequest, X402PaymentAccept, X402PaymentRequirement, X402ProjectionStatus, X402Receipt, X402ReceiptListResponse, X402ReceiptResponse, X402ReceiptStatus, X402Resource, X402ResourceStatus, X402ResourceStatusResponse, createSecureMessageRequestSchema, isX402PaymentRequired, isX402ResourceStatus, secureMessageMetadataSchema, secureMessageSchema } from 'spaps-types';
 
 /**
  * Permission checking utilities for SPAPS SDK
@@ -244,6 +244,8 @@ declare class WebSocketAuthHelper {
 }
 
 type ApiKeyType = 'publishable' | 'secret';
+/** Returns custom headers to merge into every SDK request. Called per request. */
+type HeaderProvider = () => Record<string, string>;
 interface SPAPSConfig {
     apiUrl?: string;
     /** @deprecated Use publishableKey or secretKey instead */
@@ -254,6 +256,10 @@ interface SPAPSConfig {
     secretKey?: string;
     autoDetect?: boolean;
     timeout?: number;
+    /** Additive custom header provider. Called on each request.
+     *  Returned headers are merged but cannot override SDK-managed
+     *  `Authorization` or `X-API-Key` headers. */
+    headerProvider?: HeaderProvider;
 }
 interface CheckoutLineItemPriceData {
     currency: string;
@@ -354,6 +360,158 @@ interface IssueReportListParams {
 interface IssueReportStatusParams {
     scope?: SupportedIssueReportScope;
 }
+declare class X402PaymentRequiredSDKError extends Error {
+    readonly paymentRequiredHeader: string;
+    readonly response: unknown;
+    constructor(paymentRequiredHeader: string, response: unknown);
+}
+interface X402ExecuteActionOptions {
+    paymentSignature?: string;
+    target: string;
+    bridgeToken?: string;
+    bridge_token?: string;
+}
+interface X402ReceiptListParams {
+    resourceKey?: string;
+    limit?: number;
+    offset?: number;
+}
+interface X402VerifyHandoffOptions {
+    resourceKey: string;
+    actionKey: string;
+}
+type SkillEvalDisclosurePolicy = 'blind_then_controlled_reveal';
+type SkillEvalEligibilitySource = 'admin_assigned' | 'entitlement' | 'policy_import' | 'manual_override';
+type SkillEvalConfidence = 'low' | 'medium' | 'high';
+type SkillEvalPosterResponse = 'accepted' | 'rejected' | 'needs_clarification' | 'applied';
+type SkillEvalRevealField = 'skill_version_digest' | 'provenance_ref';
+type SkillEvalGovernancePurpose = 'adopt_skill' | 'retire_skill' | 'merge_skill' | 'split_skill' | 'reviewer_policy' | 'fund_bounty';
+interface SkillEvalCandidateInput {
+    candidate_id: string;
+    output_ref: string;
+    evidence_summary: string;
+    artifact_hash: string;
+    artifact_mime: string;
+    skill_version_digest: string;
+    provenance_ref: string;
+}
+interface SkillEvalReviewerEligibilityInput {
+    reviewer_actor_id: string;
+    eligibility_source?: SkillEvalEligibilitySource;
+}
+interface CreateSkillEvalCaseRequest {
+    title: string;
+    task_claim: string;
+    success_criteria: string[];
+    candidates: SkillEvalCandidateInput[];
+    disclosure_policy?: SkillEvalDisclosurePolicy;
+    idempotency_key: string;
+    reviewer_eligibility?: SkillEvalReviewerEligibilityInput[];
+}
+interface SkillEvalCreateOptions {
+    paymentSignature?: string;
+}
+interface SkillEvalMutationOptions {
+    ifMatch?: string | number;
+    caseVersion?: number;
+}
+interface SkillEvalCaseResponse {
+    case_id: string;
+    status: string;
+    review_room_url?: string;
+    x402_action_key?: string;
+    x402_receipt_id?: string | null;
+    payload_fingerprint?: string;
+    case_version: number;
+    created_at?: string | null;
+    updated_at?: string | null;
+    idempotent_replay?: boolean;
+    title?: string;
+    task_claim?: string;
+    success_criteria?: string[];
+    candidates?: SkillEvalCandidateResponse[];
+}
+interface SkillEvalCandidateResponse {
+    candidate_id: string;
+    output_ref: string;
+    evidence_summary: string;
+    artifact_hash: string;
+    artifact_mime: string;
+    skill_version_digest?: string;
+    provenance_ref?: string;
+}
+interface SkillEvalReviewRoom {
+    case_id: string;
+    status: string;
+    task_claim: string;
+    success_criteria: string[];
+    candidates: SkillEvalCandidateResponse[];
+    reviewer_state: string;
+    case_version: number;
+}
+interface SubmitSkillEvalReviewRequest {
+    winner_candidate_id: string;
+    rationale: string;
+    missing_from_winner: string;
+    criteria_challenge?: string | null;
+    confidence: SkillEvalConfidence;
+}
+interface SkillEvalRewardEvent {
+    reward_event_id?: string;
+    event_kind: 'participation' | 'accepted_insight' | 'applied_insight' | 'delayed_bonus_candidate';
+}
+interface SkillEvalReviewResponse {
+    review_id: string;
+    status: string;
+    reward_event?: SkillEvalRewardEvent | null;
+}
+interface RespondToSkillEvalReviewRequest {
+    response: SkillEvalPosterResponse;
+    reason: string;
+    skill_change_ref?: string | null;
+}
+interface SkillEvalPosterResponseResult {
+    response_id: string;
+    response: SkillEvalPosterResponse;
+    skill_change_ref?: string | null;
+    reward_event?: SkillEvalRewardEvent | null;
+}
+interface RevealSkillEvalEvidenceRequest {
+    fields: SkillEvalRevealField[];
+    reason: string;
+}
+interface SkillEvalRevealResult {
+    reveal_id: string;
+    case_id: string;
+    status: string;
+    revealed_fields: SkillEvalRevealField[];
+}
+interface CreateSkillEvalGovernanceSnapshotRequest {
+    proposal_purpose: SkillEvalGovernancePurpose;
+    summary?: Record<string, unknown>;
+    realms_proposal_ref?: string | null;
+}
+interface SkillEvalGovernanceSnapshotResult {
+    snapshot_id: string;
+    case_id: string;
+    summary: Record<string, unknown>;
+    content_hash: string;
+    proposal_purpose: SkillEvalGovernancePurpose;
+    realms_proposal_ref?: string | null;
+    status: string;
+}
+interface ImportSkillEvalGovernanceOutcomeRequest {
+    outcome_status: string;
+    realms_proposal_ref?: string | null;
+    outcome_ref?: string | null;
+    notes?: Record<string, unknown>;
+}
+interface SkillEvalGovernanceOutcomeResult {
+    snapshot_id: string;
+    case_id: string;
+    status: string;
+    realms_proposal_ref?: string | null;
+}
 
 declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Record<string, any>> {
     private client;
@@ -361,10 +519,17 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
     private accessToken?;
     private refreshToken?;
     private _isLocalMode;
+    private headerProvider?;
     private unwrapApiResponse;
+    private skillEvalMutationConfig;
     private isAxiosResponse;
     private isResponseLikeWithData;
     private isApiResponse;
+    private static isSdkManagedHeader;
+    private static hasHeader;
+    private static setHeader;
+    private static assertSafeHeaderValue;
+    private applyCustomHeaders;
     admin: {
         createProduct: (productData: CreateProductRequest) => Promise<{
             data: Product;
@@ -472,6 +637,22 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
          */
         reply: (issueReportId: string, payload: ReplyIssueReportRequest) => Promise<IssueReport>;
     };
+    /**
+     * Application-scoped short links for browser apps that need stable public URLs.
+     */
+    appLinks: {
+        /**
+         * Create a short link owned by the authenticated user.
+         */
+        create: (payload: CreateAppLinkRequest) => Promise<AppLink>;
+        /**
+         * Resolve a public short link for the active application.
+         */
+        get: (username: string, slug: string, options?: {
+            track?: boolean;
+        }) => Promise<AppLink>;
+    };
+    private static envVar;
     constructor(config?: SPAPSConfig);
     /** Raw API request helper that returns an ApiResponse-like shape */
     request<T = any>(method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', url: string, data?: any, requiresAuth?: boolean): Promise<{
@@ -749,6 +930,31 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
             message: string;
         }>;
     };
+    /**
+     * x402 paid-resource namespace.
+     * Handles resource status checks, payment-gated actions, receipts, and handoff authorization.
+     */
+    x402: {
+        getResourceStatus: (resourceKey: string) => Promise<X402ResourceStatusResponse>;
+        executeAction: (resourceKey: string, actionKey: string, options: X402ExecuteActionOptions) => Promise<X402ActionResponse>;
+        getReceipt: (receiptId: string) => Promise<X402ReceiptResponse>;
+        listReceipts: (params?: X402ReceiptListParams) => Promise<X402ReceiptListResponse>;
+        verifyHandoff: (token: string, target: string, bridgeToken: string, options: X402VerifyHandoffOptions) => Promise<X402HandoffVerification>;
+    };
+    /**
+     * Blind comparative skill-eval namespace.
+     */
+    skillEvals: {
+        createCase: (payload: CreateSkillEvalCaseRequest, options?: SkillEvalCreateOptions) => Promise<SkillEvalCaseResponse>;
+        getCase: (caseId: string) => Promise<SkillEvalCaseResponse>;
+        getReviewRoom: (caseId: string) => Promise<SkillEvalReviewRoom>;
+        submitReview: (caseId: string, payload: SubmitSkillEvalReviewRequest, options?: SkillEvalMutationOptions) => Promise<SkillEvalReviewResponse>;
+        respondToReview: (caseId: string, reviewId: string, payload: RespondToSkillEvalReviewRequest, options?: SkillEvalMutationOptions) => Promise<SkillEvalPosterResponseResult>;
+        lockReviews: (caseId: string, options?: SkillEvalMutationOptions) => Promise<SkillEvalCaseResponse>;
+        revealEvidence: (caseId: string, payload: RevealSkillEvalEvidenceRequest, options?: SkillEvalMutationOptions) => Promise<SkillEvalRevealResult>;
+        createGovernanceSnapshot: (caseId: string, payload: CreateSkillEvalGovernanceSnapshotRequest, options?: SkillEvalMutationOptions) => Promise<SkillEvalGovernanceSnapshotResult>;
+        importGovernanceOutcome: (snapshotId: string, payload: ImportSkillEvalGovernanceOutcomeRequest) => Promise<SkillEvalGovernanceOutcomeResult>;
+    };
     /**
      * DayRate (Dynamic Scheduling) namespace
      * For booking half-day sessions with dynamic pricing
@@ -769,6 +975,14 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
          * Reserves multiple slots with a single checkout session
          */
         createMultiBooking: (payload: DayrateMultiBookingRequest) => Promise<DayrateMultiBookingResponse>;
+        /**
+         * Create a single-slot booking hold backed by an x402 paid-resource action.
+         */
+        createX402Booking: (payload: DayrateX402BookingRequest) => Promise<DayrateX402BookingResponse>;
+        /**
+         * Get guest-safe checkout confirmation state for a Stripe session.
+         */
+        getCheckoutStatus: (sessionId: string) => Promise<DayrateCheckoutStatusResponse>;
     };
     createCheckoutSession(priceId: string, successUrl: string, cancelUrl?: string): Promise<{
         data: CheckoutSession;
@@ -878,6 +1092,7 @@ declare class TokenManager {
     static getRefreshToken(): string | null;
     static getStoredUser(): User$1 | null;
     static clearTokens(): void;
+    static decodePayload(token: string): Record<string, unknown> | null;
     static isTokenExpired(token: string): boolean;
     static autoRefreshToken(sdk: SPAPSClient): Promise<boolean>;
     /**
@@ -903,6 +1118,29 @@ declare class WalletUtils {
     static detectChainType(address: string): 'solana' | 'ethereum' | 'bitcoin' | null;
     static isValidAddress(address: string, chainType?: 'solana' | 'ethereum' | 'bitcoin' | 'base'): boolean;
 }
+interface SPAPSEnvelope<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+declare function isEnvelope(value: unknown): value is SPAPSEnvelope;
+declare function isSuccessEnvelope<T = unknown>(value: unknown): value is SPAPSEnvelope<T> & {
+    success: true;
+};
+declare function isErrorEnvelope(value: unknown): value is SPAPSEnvelope & {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+};
+declare function unwrapEnvelope<T = unknown>(value: unknown, fallbackMessage?: string): T;
+declare function unwrapNestedData<T = unknown>(value: unknown): T;
 /**
  * Create a SPAPS client for browser/client-side usage
  * Uses publishable key which is safe to expose in client bundles
@@ -938,4 +1176,4 @@ declare function createServerClient(secretKey: string, options?: Omit<SPAPSConfi
  */
 declare function detectKeyType(key: string): ApiKeyType | null;
 
-export { type AdminConfig, type ApiKeyType, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, DEFAULT_ADMIN_ACCOUNTS, type EmailSendOptions, type EmailSendResult, type EmailTemplate, type EmailTemplatePreview, type EntitlementCheckResult, type EntitlementListParams, type FeatureContext, type FeatureDefinition, FeatureEvaluator, type IssueReportListParams, type IssueReportStatusParams, type PermissionCheckResult, PermissionChecker, RoleHierarchy, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type TemplateVariable, TokenManager, WalletUtils, WebSocketAuthHelper, type WebSocketAuthHelperConfig, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, verifyCryptoWebhookSignature };
+export { type AdminConfig, type ApiKeyType, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, type CreateSkillEvalCaseRequest, type CreateSkillEvalGovernanceSnapshotRequest, DEFAULT_ADMIN_ACCOUNTS, type EmailSendOptions, type EmailSendResult, type EmailTemplate, type EmailTemplatePreview, type EntitlementCheckResult, type EntitlementListParams, type FeatureContext, type FeatureDefinition, FeatureEvaluator, type HeaderProvider, type ImportSkillEvalGovernanceOutcomeRequest, type IssueReportListParams, type IssueReportStatusParams, type PermissionCheckResult, PermissionChecker, type RespondToSkillEvalReviewRequest, type RevealSkillEvalEvidenceRequest, RoleHierarchy, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type SPAPSEnvelope, type SkillEvalCandidateInput, type SkillEvalCandidateResponse, type SkillEvalCaseResponse, type SkillEvalConfidence, type SkillEvalCreateOptions, type SkillEvalDisclosurePolicy, type SkillEvalEligibilitySource, type SkillEvalGovernanceOutcomeResult, type SkillEvalGovernancePurpose, type SkillEvalGovernanceSnapshotResult, type SkillEvalMutationOptions, type SkillEvalPosterResponse, type SkillEvalPosterResponseResult, type SkillEvalRevealField, type SkillEvalRevealResult, type SkillEvalReviewResponse, type SkillEvalReviewRoom, type SkillEvalReviewerEligibilityInput, type SkillEvalRewardEvent, type SubmitSkillEvalReviewRequest, type TemplateVariable, TokenManager, WalletUtils, WebSocketAuthHelper, type WebSocketAuthHelperConfig, 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 };