spaps-sdk 1.10.0 → 1.10.2

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
+### Added
+
+- Added `issueReporting.getAttachmentAccess(attachmentId)` as the canonical screenshot access helper while keeping `getAttachmentAccessUrl` as a backward-compatible alias.
+
+## [1.10.1] - 2026-05-16
+
+### Added
+
+- Added issue-reporting screenshot attachment helpers for private upload, list, access URL, delete, and attach-by-ID create/update/reply flows.
+
+## [1.10.0] - 2026-05-11
+
+- Added usage-control SDK support for authorizing usage and recording immutable usage events against SPAPS.
+
+## [1.9.0] - 2026-05-11
+
+- Maintenance: align the SDK package version after release automation.
+
 ## [1.8.0] - 2026-05-11
 
 - Maintenance: align the SDK package version after release automation.

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`, `appLinks`, `email`, `entitlements`, `usage`, `skillEvals`, `dayrate`, `admin`, and `cfo` namespaces |
+| One client for many SPAPS surfaces | `auth`, `payments`, `sessions`, `secureMessages`, `issueReporting`, `appLinks`, `marketing`, `email`, `entitlements`, `usage`, `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` |
@@ -84,8 +84,9 @@ Relevant environment variables:
 | `payments` | Checkout sessions, products, prices, subscriptions, and crypto helpers |
 | `sessions` | Session lookup, validation, and lifecycle helpers |
 | `secureMessages` | Secure-message create/list helpers |
-| `issueReporting` | Status, history, create, update, reply, and voice-token flows |
+| `issueReporting` | Status, history, create, update, reply, voice-token, and private screenshot attachment flows |
 | `appLinks` | Authenticated create and public resolve helpers for application-scoped short links |
+| `marketing` | Browser-safe attribution/experiment event emission and server-side experiment results |
 | `email` | Template lookup, preview, and send helpers |
 | `entitlements` | User and resource entitlement queries |
 | `usage` | Secret-key usage authorization and immutable usage recording |
@@ -124,6 +125,37 @@ const voiceToken = await spaps.issueReporting.createVoiceToken();
 console.log(voiceToken.provider, voiceToken.model_id);
 ```
 
+### Issue Reporting Screenshot Attachments
+
+Screenshots are uploaded as private pending hosted assets first. Create, update, or reply calls then send only attachment IDs; do not put raw image bytes, data URLs, or base64 payloads in issue notes or target metadata.
+
+```ts
+spaps.setAccessToken(accessToken);
+
+const file = new File([pngBytes], "protocol-save-failure.png", {
+  type: "image/png",
+});
+const attachment = await spaps.issueReporting.uploadAttachment(file);
+
+const issue = await spaps.issueReporting.create({
+  target: {
+    component_key: "patient_protocol_widget",
+    component_label: "Patient Protocol Widget",
+    page_url: "/patients/123/protocol",
+    surface_ref: "daily-log",
+    metadata: { section: "daily log" },
+  },
+  note: "The save action silently fails after I edit today's protocol note.",
+  reporter_role_hint: "practitioner",
+  attachment_ids: [attachment.id],
+});
+
+const access = await spaps.issueReporting.getAttachmentAccess(attachment.id);
+console.log(issue.id, access.expires_in_seconds);
+```
+
+SPAPS accepts PNG, JPEG, and WebP screenshots up to 10 MiB each, with at most 5 retained screenshots per report. The hosted object remains private; callers fetch a short-lived access URL after normal issue-reporting authorization succeeds. SPAPS does not redact screenshot contents, so host apps should warn users when a capture may include sensitive data.
+
 ### Application Short Links
 
 Use `appLinks` when a browser app needs a stable public URL for large local state, such as compressed diagram state.
@@ -143,6 +175,41 @@ const link = await spaps.appLinks.create({
 });
 
 console.log(`/${link.app_slug}/${link.username}/${link.slug}`);
+
+await spaps.appLinks.update(link.username, link.slug, {
+  metadata: { diagram_state: "pako:new-state" },
+});
+```
+
+### Marketing Events
+
+Use `marketing.emit` in the browser with a publishable key for anonymous
+attribution touches or experiment exposures. Use `marketing.getExperimentResults`
+from a trusted server or agent with a secret key to read revenue-backed results
+and the conservative stop signal.
+
+```ts
+const browserSpaps = new SPAPSClient({
+  apiUrl: "https://api.example.test",
+  publishableKey: "spaps_pub_example",
+});
+
+await browserSpaps.marketing.emit({
+  anon_id: "anon_01HY...",
+  event_type: "experiment_exposure",
+  experiment_id: "landing-hero-copy",
+  variant_id: "treatment",
+  dedupe_key: "landing-hero-copy:anon_01HY:treatment",
+  timestamp: new Date().toISOString(),
+});
+
+const serverSpaps = new SPAPSClient({
+  apiUrl: "https://api.example.test",
+  secretKey: process.env.SPAPS_SECRET_KEY,
+});
+
+const results = await serverSpaps.marketing.getExperimentResults("landing-hero-copy");
+console.log(results.decision.recommendation, results.decision.winner_variant_id);
 ```
 
 ### Server-Side Usage Control
@@ -192,8 +259,9 @@ await spaps.usage.record({
 });
 ```
 
-The legacy `/api/usage/features` and `/api/usage/history` routes remain
-not-implemented stubs and are not exposed through this SDK namespace.
+For dashboard and policy views, use `spaps.usage.listFeatures()`,
+`spaps.usage.getStatus(...)`, and `spaps.usage.listHistory(...)` from the same
+trusted backend context.
 
 ### Skill Evals
 
@@ -416,7 +484,7 @@ npm run test:readme
 ## Metadata
 
 - `package_name`: `spaps-sdk`
-- `latest_version`: `1.8.0`
+- `latest_version`: `1.10.1`
 - `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, CreateAppLinkRequest, AppLink, AuthResponse, User as User$1, CreateCryptoInvoiceRequest, CryptoInvoiceStatusSnapshot, CheckoutSession, X402ResourceStatusResponse, X402ActionResponse, X402ReceiptResponse, X402ReceiptListResponse, X402HandoffVerification, DayrateAvailabilityResponse, DayrateBookingRequest, DayrateBookingResponse, DayrateMultiBookingRequest, DayrateMultiBookingResponse, DayrateX402BookingRequest, DayrateX402BookingResponse, DayrateCheckoutStatusResponse, UsageControlAuthorizeRequest, UsageControlAuthorizeResponse, UsageControlRecordRequest, UsageControlRecordResponse, Subscription, 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, UsageControlAuthorizeRequest, UsageControlAuthorizeResponse, UsageControlDecision, UsageControlDimensions, UsageControlError, UsageControlErrorCode, UsageControlLedgerEvent, UsageControlRecordRequest, UsageControlRecordResponse, UsageControlRecordStatus, 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, atomicToMoneyUnits, createSecureMessageRequestSchema, isX402PaymentRequired, isX402ResourceStatus, moneyUnitsToAtomic, roundHalfToPositiveInfinity, secureMessageMetadataSchema, secureMessageSchema, validatePositiveAmountAtomic } from 'spaps-types';
+import { ResourceType, Entitlement, CreateProductRequest, Product, UpdateProductRequest, CreatePriceRequest, Price, ProductSyncResult, CryptoReconcileRequest, CreateSecureMessageRequest, SecureMessage, IssueReportScope, IssueReportStatusResult, IssueReportStatus, IssueReportListResult, IssueReport, CreateIssueReportRequest, IssueReportAttachmentOut, ListIssueReportAttachmentsResponse, IssueReportAttachmentAccessResponse, IssueReportingVoiceTokenResult, UpdateIssueReportRequest, ReplyIssueReportRequest, ListIssueReportMessagesResponse, CreateReporterMessageRequest, IssueReportMessage, CreateOperatorMessageRequest, RetractOperatorMessageRequest, CreateAppLinkRequest, AppLink, UpdateAppLinkRequest, AuthResponse, User as User$1, CreateCryptoInvoiceRequest, CryptoInvoiceStatusSnapshot, CheckoutSession, X402ResourceStatusResponse, X402ActionResponse, X402ReceiptResponse, X402ReceiptListResponse, X402HandoffVerification, DayrateAvailabilityResponse, DayrateBookingRequest, DayrateBookingResponse, DayrateMultiBookingRequest, DayrateMultiBookingResponse, DayrateX402BookingRequest, DayrateX402BookingResponse, DayrateCheckoutStatusResponse, UsageControlFeaturesResponse, UsageControlStatusRequest, UsageControlStatusResponse, UsageControlAuthorizeRequest, UsageControlAuthorizeResponse, UsageControlRecordRequest, UsageControlRecordResponse, UsageControlHistoryRequest, UsageControlHistoryResponse, Subscription, VerifyCryptoWebhookSignatureOptions } from 'spaps-types';
+export { AdminPermission, AdminRole, AdminUser, ApiResponse, AppLink, AuthResponse, CheckoutSession, CreateAppLinkRequest, CreateCryptoInvoiceRequest, CreateIssueReportRequest, CreateOperatorMessageRequest, CreatePriceRequest, CreateProductRequest, CreateReporterMessageRequest, CreateSecureMessageInput, CreateSecureMessageRequest, CryptoInvoice, CryptoInvoiceResponse, CryptoInvoiceStatusSnapshot, CryptoReconcileRequest, DayrateAvailabilityResponse, DayrateAvailableSlot, DayrateBookingRequest, DayrateBookingResponse, DayrateCheckoutStatus, DayrateCheckoutStatusBooking, DayrateCheckoutStatusResponse, DayrateDayOfWeek, DayrateMultiBookingRequest, DayrateMultiBookingResponse, DayratePriceBreakdown, DayrateSlotType, DayrateX402BookingRequest, DayrateX402BookingResponse, Entitlement, IssueReport, IssueReportAttachmentAccessResponse, IssueReportAttachmentOut, IssueReportListResult, IssueReportMessage, IssueReportStatus, IssueReportStatusResult, IssueReportTarget, IssueReportingInputMode, IssueReportingVoiceProvider, IssueReportingVoiceTokenResult, LinkedIssueReportCase, ListIssueReportAttachmentsResponse, ListIssueReportMessagesResponse, Price, Product, ProductSyncResult, ReplyIssueReportRequest, ResourceType, RetractOperatorMessageRequest, SecureMessage, SecureMessageOutput, Subscription, TokenPair, UpdateAppLinkRequest, UpdateIssueReportRequest, UpdateProductRequest, UsageControlAuthorizeRequest, UsageControlAuthorizeResponse, UsageControlDecision, UsageControlDimensions, UsageControlError, UsageControlErrorCode, UsageControlFeaturesResponse, UsageControlHistoryRequest, UsageControlHistoryResponse, UsageControlLedgerEvent, UsageControlRecordRequest, UsageControlRecordResponse, UsageControlRecordStatus, UsageControlStatusRequest, UsageControlStatusResponse, 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, atomicToMoneyUnits, createSecureMessageRequestSchema, isX402PaymentRequired, isX402ResourceStatus, moneyUnitsToAtomic, roundHalfToPositiveInfinity, secureMessageMetadataSchema, secureMessageSchema, validatePositiveAmountAtomic } from 'spaps-types';
 
 /**
  * Permission checking utilities for SPAPS SDK
@@ -336,6 +336,73 @@ interface EmailTemplatePreview {
     html: string;
     text?: string;
 }
+type MarketingEventType = 'attribution_touch' | 'experiment_exposure';
+type MarketingExperimentRecommendation = 'continue' | 'continue_srm_warning' | 'stop_for_winner';
+type MarketingExperimentSrmStatus = 'pass' | 'warning' | 'not_applicable';
+interface MarketingEventIngestRequest {
+    application_id?: string;
+    anon_id: string;
+    event_type: MarketingEventType;
+    experiment_id?: string | null;
+    variant_id?: string | null;
+    variant?: string | null;
+    metadata?: Record<string, unknown> | null;
+    dedupe_key?: string | null;
+    timestamp?: string | null;
+    observed_at?: string | null;
+}
+interface MarketingEventIngestResponse {
+    id: string;
+    application_id: string;
+    anon_id: string;
+    event_type: MarketingEventType;
+    experiment_id?: string | null;
+    variant?: string | null;
+    dedupe_key: string;
+    ts: string;
+    created_at: string;
+}
+interface MarketingExperimentVariantResult {
+    variant_id: string | null;
+    exposures: number;
+    conversions: number;
+    conversion_rate: number;
+    revenue: Record<string, number>;
+}
+interface MarketingExperimentMinSampleDecision {
+    met: boolean;
+    min_exposures_per_variant: number;
+    min_total_conversions: number;
+    observed_min_exposures: number;
+    observed_total_conversions: number;
+}
+interface MarketingExperimentSrmDecision {
+    status: MarketingExperimentSrmStatus;
+    expected_share?: number | null;
+    max_share_ratio?: number | null;
+    min_share_ratio?: number | null;
+}
+interface MarketingExperimentEffectDecision {
+    leader_variant_id?: string | null;
+    runner_up_variant_id?: string | null;
+    absolute_lift?: number | null;
+    relative_lift?: number | null;
+}
+interface MarketingExperimentDecision {
+    decisive: boolean;
+    recommendation: MarketingExperimentRecommendation;
+    winner_variant_id?: string | null;
+    reason_codes: string[];
+    min_sample: MarketingExperimentMinSampleDecision;
+    srm: MarketingExperimentSrmDecision;
+    effect: MarketingExperimentEffectDecision;
+}
+interface MarketingExperimentResultsResponse {
+    application_id: string;
+    experiment_id: string;
+    variants: MarketingExperimentVariantResult[];
+    decision: MarketingExperimentDecision;
+}
 interface EntitlementListParams {
     /** Filter by entitlement key */
     key?: string;
@@ -360,6 +427,9 @@ interface IssueReportListParams {
 interface IssueReportStatusParams {
     scope?: SupportedIssueReportScope;
 }
+interface IssueReportAttachmentUploadOptions {
+    filename?: string;
+}
 declare class X402PaymentRequiredSDKError extends Error {
     readonly paymentRequiredHeader: string;
     readonly response: unknown;
@@ -705,7 +775,7 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
          * Note: For publishable key contexts, only `resource_type=user` is permitted.
          * Non-user resource types will return a 403 error (enforced server-side).
          *
-         * @param resourceType - The resource type (e.g. "user", "company", "org", "system").
+         * @param resourceType - The resource type (e.g. "user", "company", "org", "system", "project").
          * @param resourceId - Optional specific resource ID.
          */
         listByResource: (resourceType: ResourceType, resourceId?: string) => Promise<Entitlement[]>;
@@ -730,6 +800,28 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
          * Create a new canonical issue report.
          */
         create: (payload: CreateIssueReportRequest) => Promise<IssueReport>;
+        /**
+         * Upload one private pending screenshot attachment.
+         */
+        uploadAttachment: (file: Blob, options?: IssueReportAttachmentUploadOptions) => Promise<IssueReportAttachmentOut>;
+        /**
+         * List non-deleted screenshot attachments for one issue report.
+         */
+        listAttachments: (issueReportId: string) => Promise<ListIssueReportAttachmentsResponse>;
+        /**
+         * Return a short-lived private attachment access URL.
+         */
+        getAttachmentAccess: (attachmentId: string) => Promise<IssueReportAttachmentAccessResponse>;
+        /**
+         * Return a short-lived private attachment access URL.
+         *
+         * @deprecated Use getAttachmentAccess(attachmentId).
+         */
+        getAttachmentAccessUrl: (attachmentId: string) => Promise<IssueReportAttachmentAccessResponse>;
+        /**
+         * Soft-delete one owned screenshot attachment.
+         */
+        deleteAttachment: (attachmentId: string) => Promise<void>;
         /**
          * Create a short-lived voice transcription token for issue reporting.
          */
@@ -742,6 +834,46 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
          * Reply to a resolved or ignored issue report and reopen the linked case.
          */
         reply: (issueReportId: string, payload: ReplyIssueReportRequest) => Promise<IssueReport>;
+        /**
+         * List the chronological, reporter-visible message thread for one owned
+         * issue report. Only active, reporter-visible rows are returned; retracted
+         * or superseded operator messages are excluded and raw audit payloads are
+         * never exposed. `needs_response` badges an open clarification request.
+         */
+        listMessages: (issueReportId: string) => Promise<ListIssueReportMessagesResponse>;
+        /**
+         * Submit a reporter clarification response on one owned issue report. This
+         * does NOT reopen a closed case (use `reply` for that). Idempotent on
+         * `idempotency_key`: same key + same body returns the existing message,
+         * same key + different body returns 409 ISSUE_REPORT_MESSAGE_CONFLICT.
+         */
+        submitMessage: (issueReportId: string, payload: CreateReporterMessageRequest) => Promise<IssueReportMessage>;
+        /**
+         * Triage-operator message commands. These require a secret key context and a
+         * triage role/capability; publishable browser contexts are rejected by the
+         * server. Provide the secret key as the SDK's API key.
+         */
+        triage: {
+            /**
+             * List all projection rows for an app-scoped report (including corrected
+             * rows) for authorized triage operators.
+             */
+            listMessages: (issueReportId: string) => Promise<ListIssueReportMessagesResponse>;
+            /**
+             * Post a clarification_request or final_response reporter-visible message
+             * as a triage operator. Idempotent on `idempotency_key`; a key reused with
+             * a different body returns 409. A final_response can drive a terminal
+             * lifecycle transition via `resolve_case`; the internal resolution_note is
+             * never auto-displayed to reporters.
+             */
+            postMessage: (issueReportId: string, payload: CreateOperatorMessageRequest) => Promise<IssueReportMessage>;
+            /**
+             * Retract an operator-authored message. The body is retained; the row's
+             * state is marked `retracted`. Retracting an already-retracted message is
+             * a safe no-op.
+             */
+            retractMessage: (issueReportId: string, messageId: string, payload?: RetractOperatorMessageRequest) => Promise<IssueReportMessage>;
+        };
     };
     /**
      * Application-scoped short links for browser apps that need stable public URLs.
@@ -751,6 +883,10 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
          * Create a short link owned by the authenticated user.
          */
         create: (payload: CreateAppLinkRequest) => Promise<AppLink>;
+        /**
+         * Update a short link owned by the authenticated user.
+         */
+        update: (username: string, slug: string, payload: UpdateAppLinkRequest) => Promise<AppLink>;
         /**
          * Resolve a public short link for the active application.
          */
@@ -758,6 +894,30 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
             track?: boolean;
         }) => Promise<AppLink>;
     };
+    /**
+     * Marketing events and experiment results.
+     *
+     * Use a publishable key for browser-side event emission. Use a secret key
+     * from a trusted server or agent process when reading experiment results.
+     */
+    marketing: {
+        /**
+         * Emit one anonymous attribution touch or experiment exposure.
+         */
+        emit: (payload: MarketingEventIngestRequest) => Promise<MarketingEventIngestResponse>;
+        /**
+         * Alias for emit(), matching the backend ingest endpoint language.
+         */
+        ingest: (payload: MarketingEventIngestRequest) => Promise<MarketingEventIngestResponse>;
+        /**
+         * Read per-variant experiment results and the conservative stop signal.
+         */
+        getExperimentResults: (experimentId: string) => Promise<MarketingExperimentResultsResponse>;
+        /**
+         * Short alias for getExperimentResults().
+         */
+        getResults: (experimentId: string) => Promise<MarketingExperimentResultsResponse>;
+    };
     private static envVar;
     constructor(config?: SPAPSConfig);
     /** Raw API request helper that returns an ApiResponse-like shape */
@@ -963,7 +1123,7 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
         updateProductSuperAdmin: (productId: string, updates: any) => Promise<any>;
         deleteProductSuperAdmin: (productId: string) => Promise<any>;
         createProductWithPrice: (payload: any) => Promise<any>;
-        createProductWithPriceSuperAdmin: (productId: string, payload: any) => Promise<any>;
+        createProductWithPriceSuperAdmin: (applicationId: string, payload: any) => Promise<any>;
         setDefaultPrice: (productId: string, payload: {
             price_id: string;
         }) => Promise<any>;
@@ -1099,6 +1259,14 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
      * after work completes.
      */
     usage: {
+        /**
+         * List active usage feature definitions for this application.
+         */
+        listFeatures: () => Promise<UsageControlFeaturesResponse>;
+        /**
+         * Fetch current window usage status without creating an authorization.
+         */
+        getStatus: (query: UsageControlStatusRequest) => Promise<UsageControlStatusResponse>;
         /**
          * Authorize proposed usage before a downstream job, inference, or action runs.
          */
@@ -1107,16 +1275,28 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
          * Record immutable usage after work completes.
          */
         record: (payload: UsageControlRecordRequest) => Promise<UsageControlRecordResponse>;
+        /**
+         * List usage events in deterministic newest-first order.
+         */
+        listHistory: (query?: UsageControlHistoryRequest) => Promise<UsageControlHistoryResponse>;
     };
     createCheckoutSession(priceId: string, successUrl: string, cancelUrl?: string): Promise<{
         data: CheckoutSession;
     }>;
-    getSubscription(): Promise<{
+    getSubscription(subscriptionId?: string): Promise<{
+        data: Subscription | Subscription[];
+    }>;
+    cancelSubscription(subscriptionId?: string, options?: {
+        immediately?: boolean;
+    }): Promise<{
         data: Subscription;
     }>;
-    cancelSubscription(): Promise<void>;
     authorizeUsage(payload: UsageControlAuthorizeRequest): Promise<UsageControlAuthorizeResponse>;
     recordUsage(payload: UsageControlRecordRequest): Promise<UsageControlRecordResponse>;
+    getUsageStatus(query: UsageControlStatusRequest): Promise<UsageControlStatusResponse>;
+    listUsageHistory(query?: UsageControlHistoryRequest): Promise<UsageControlHistoryResponse>;
+    emitMarketingEvent(payload: MarketingEventIngestRequest): Promise<MarketingEventIngestResponse>;
+    getMarketingExperimentResults(experimentId: string): Promise<MarketingExperimentResultsResponse>;
     private createSecureMessage;
     private listSecureMessages;
     /**
@@ -1298,4 +1478,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, 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 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 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 };
+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 IssueReportAttachmentUploadOptions, type IssueReportListParams, type IssueReportStatusParams, type MarketingEventIngestRequest, type MarketingEventIngestResponse, type MarketingEventType, type MarketingExperimentDecision, type MarketingExperimentEffectDecision, type MarketingExperimentMinSampleDecision, type MarketingExperimentRecommendation, type MarketingExperimentResultsResponse, type MarketingExperimentSrmDecision, type MarketingExperimentSrmStatus, type MarketingExperimentVariantResult, type PermissionCheckResult, PermissionChecker, type RespondToSkillEvalReviewRequest, type RevealSkillEvalEvidenceRequest, RoleHierarchy, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type SPAPSEnvelope, 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 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 };