spaps-sdk 1.6.8 → 1.7.0

package/dist/index.d.ts

@@ -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 };