spaps-sdk 1.9.0 → 1.10.1

package/CHANGELOG.md

@@ -6,6 +6,18 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
+### 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`, `skillEvals`, `dayrate`, `admin`, and `cfo` namespaces |
+| One client for many SPAPS surfaces | `auth`, `payments`, `sessions`, `secureMessages`, `issueReporting`, `appLinks`, `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,10 +84,11 @@ 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 |
 | `email` | Template lookup, preview, and send helpers |
 | `entitlements` | User and resource entitlement queries |
+| `usage` | Secret-key usage authorization and immutable usage recording |
 | `skillEvals` | Paid blind skill-eval cases, review rooms, reviewer marks, insight inboxes, and controlled reveal |
 | `dayrate` | Availability, Stripe booking, x402 booking-hold, and checkout-status helpers |
 | `admin` | Product and pricing admin helpers |
@@ -123,6 +124,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.getAttachmentAccessUrl(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.
@@ -144,6 +176,57 @@ const link = await spaps.appLinks.create({
 console.log(`/${link.app_slug}/${link.username}/${link.slug}`);
 ```
 
+### Server-Side Usage Control
+
+Use `usage` from a trusted backend with a secret key. Browser apps should call
+their own backend first; that backend asks SPAPS to authorize the work, performs
+the work only on an allow or warning decision, then records the actual usage
+with a stable idempotency key.
+
+```ts
+const spaps = new SPAPSClient({
+  apiUrl: "https://api.example.test",
+  secretKey: process.env.SPAPS_SECRET_KEY,
+});
+
+const authorization = await spaps.usage.authorize({
+  feature_key: "assistant_tokens",
+  resource_type: "company",
+  resource_id: "company_123",
+  subject_user_id: "user_123",
+  dimensions: {
+    requests: 1,
+    input_tokens: 1200,
+  },
+});
+
+if (authorization.decision === "blocked") {
+  throw new Error(authorization.reasons[0]?.message || "Usage not authorized");
+}
+
+const result = await runAssistantJob();
+
+await spaps.usage.record({
+  authorization_ref: authorization.authorization_ref,
+  idempotency_key: result.jobId,
+  feature_key: "assistant_tokens",
+  resource_type: "company",
+  resource_id: "company_123",
+  subject_user_id: "user_123",
+  dimensions: {
+    input_tokens: result.inputTokens,
+    output_tokens: result.outputTokens,
+  },
+  metadata: {
+    job_id: result.jobId,
+  },
+});
+```
+
+For dashboard and policy views, use `spaps.usage.listFeatures()`,
+`spaps.usage.getStatus(...)`, and `spaps.usage.listHistory(...)` from the same
+trusted backend context.
+
 ### Skill Evals
 
 Use `skillEvals` for SPAPS-owned blind review of agent-skill logs. Paid creation uses the same `PAYMENT-SIGNATURE` header shape as the x402 namespace. Reviewers submit `valuable` and `not_valuable` marks, and submitters read those marks through an insight inbox before applying skill changes.
@@ -365,7 +448,7 @@ npm run test:readme
 ## Metadata
 
 - `package_name`: `spaps-sdk`
-- `latest_version`: `1.8.0`
+- `latest_version`: `1.10.0`
 - `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, 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, 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, CreateAppLinkRequest, AppLink, 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, CreatePriceRequest, CreateProductRequest, 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, IssueReportStatus, IssueReportStatusResult, IssueReportTarget, IssueReportingInputMode, IssueReportingVoiceProvider, IssueReportingVoiceTokenResult, LinkedIssueReportCase, ListIssueReportAttachmentsResponse, Price, Product, ProductSyncResult, ReplyIssueReportRequest, ResourceType, SecureMessage, SecureMessageOutput, Subscription, TokenPair, 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
@@ -360,6 +360,9 @@ interface IssueReportListParams {
 interface IssueReportStatusParams {
     scope?: SupportedIssueReportScope;
 }
+interface IssueReportAttachmentUploadOptions {
+    filename?: string;
+}
 declare class X402PaymentRequiredSDKError extends Error {
     readonly paymentRequiredHeader: string;
     readonly response: unknown;
@@ -730,6 +733,22 @@ 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.
+         */
+        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.
          */
@@ -963,7 +982,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>;
@@ -1091,17 +1110,50 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
          */
         getCheckoutStatus: (sessionId: string) => Promise<DayrateCheckoutStatusResponse>;
     };
+    /**
+     * Server-side usage control.
+     *
+     * These endpoints require a secret SPAPS key. Browser clients should call
+     * their own backend, then the backend should authorize before work and record
+     * 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.
+         */
+        authorize: (payload: UsageControlAuthorizeRequest) => Promise<UsageControlAuthorizeResponse>;
+        /**
+         * 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<{
-        data: Subscription;
+    getSubscription(subscriptionId?: string): Promise<{
+        data: Subscription | Subscription[];
     }>;
-    cancelSubscription(): Promise<void>;
-    getUsageBalance(): Promise<{
-        data: UsageBalance;
+    cancelSubscription(subscriptionId?: string, options?: {
+        immediately?: boolean;
+    }): Promise<{
+        data: Subscription;
     }>;
-    recordUsage(feature: string, amount: number): Promise<void>;
+    authorizeUsage(payload: UsageControlAuthorizeRequest): Promise<UsageControlAuthorizeResponse>;
+    recordUsage(payload: UsageControlRecordRequest): Promise<UsageControlRecordResponse>;
+    getUsageStatus(query: UsageControlStatusRequest): Promise<UsageControlStatusResponse>;
+    listUsageHistory(query?: UsageControlHistoryRequest): Promise<UsageControlHistoryResponse>;
     private createSecureMessage;
     private listSecureMessages;
     /**
@@ -1283,4 +1335,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 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 };

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, 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, 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, CreateAppLinkRequest, AppLink, 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, CreatePriceRequest, CreateProductRequest, 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, IssueReportStatus, IssueReportStatusResult, IssueReportTarget, IssueReportingInputMode, IssueReportingVoiceProvider, IssueReportingVoiceTokenResult, LinkedIssueReportCase, ListIssueReportAttachmentsResponse, Price, Product, ProductSyncResult, ReplyIssueReportRequest, ResourceType, SecureMessage, SecureMessageOutput, Subscription, TokenPair, 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
@@ -360,6 +360,9 @@ interface IssueReportListParams {
 interface IssueReportStatusParams {
     scope?: SupportedIssueReportScope;
 }
+interface IssueReportAttachmentUploadOptions {
+    filename?: string;
+}
 declare class X402PaymentRequiredSDKError extends Error {
     readonly paymentRequiredHeader: string;
     readonly response: unknown;
@@ -730,6 +733,22 @@ 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.
+         */
+        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.
          */
@@ -963,7 +982,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>;
@@ -1091,17 +1110,50 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
          */
         getCheckoutStatus: (sessionId: string) => Promise<DayrateCheckoutStatusResponse>;
     };
+    /**
+     * Server-side usage control.
+     *
+     * These endpoints require a secret SPAPS key. Browser clients should call
+     * their own backend, then the backend should authorize before work and record
+     * 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.
+         */
+        authorize: (payload: UsageControlAuthorizeRequest) => Promise<UsageControlAuthorizeResponse>;
+        /**
+         * 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<{
-        data: Subscription;
+    getSubscription(subscriptionId?: string): Promise<{
+        data: Subscription | Subscription[];
     }>;
-    cancelSubscription(): Promise<void>;
-    getUsageBalance(): Promise<{
-        data: UsageBalance;
+    cancelSubscription(subscriptionId?: string, options?: {
+        immediately?: boolean;
+    }): Promise<{
+        data: Subscription;
     }>;
-    recordUsage(feature: string, amount: number): Promise<void>;
+    authorizeUsage(payload: UsageControlAuthorizeRequest): Promise<UsageControlAuthorizeResponse>;
+    recordUsage(payload: UsageControlRecordRequest): Promise<UsageControlRecordResponse>;
+    getUsageStatus(query: UsageControlStatusRequest): Promise<UsageControlStatusResponse>;
+    listUsageHistory(query?: UsageControlHistoryRequest): Promise<UsageControlHistoryResponse>;
     private createSecureMessage;
     private listSecureMessages;
     /**
@@ -1283,4 +1335,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 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 };

package/dist/index.js

@@ -757,6 +757,61 @@ var SPAPSClient = class _SPAPSClient {
       );
       return this.unwrapApiResponse(res, "Failed to create issue report");
     },
+    /**
+     * Upload one private pending screenshot attachment.
+     */
+    uploadAttachment: async (file, options) => {
+      if (typeof FormData === "undefined") {
+        throw new Error("FormData is required to upload issue report attachments");
+      }
+      const formData = new FormData();
+      const fileWithOptionalName = file;
+      const inferredFilename = typeof fileWithOptionalName.name === "string" ? fileWithOptionalName.name : void 0;
+      const filename = options?.filename ?? inferredFilename;
+      if (filename) {
+        formData.append("file", file, filename);
+      } else {
+        formData.append("file", file);
+      }
+      const res = await this.client.post(
+        "/api/v1/issue-reports/attachments",
+        formData,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      return this.unwrapApiResponse(res, "Failed to upload issue report attachment");
+    },
+    /**
+     * List non-deleted screenshot attachments for one issue report.
+     */
+    listAttachments: async (issueReportId) => {
+      const res = await this.client.get(
+        `/api/v1/issue-reports/${encodeURIComponent(issueReportId)}/attachments`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      return this.unwrapApiResponse(res, "Failed to list issue report attachments");
+    },
+    /**
+     * Return a short-lived private attachment access URL.
+     */
+    getAttachmentAccessUrl: async (attachmentId) => {
+      const res = await this.client.get(
+        `/api/v1/issue-reports/attachments/${encodeURIComponent(attachmentId)}/access`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to get issue report attachment access URL"
+      );
+    },
+    /**
+     * Soft-delete one owned screenshot attachment.
+     */
+    deleteAttachment: async (attachmentId) => {
+      await this.client.delete(
+        `/api/v1/issue-reports/attachments/${encodeURIComponent(attachmentId)}`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+    },
     /**
      * Create a short-lived voice transcription token for issue reporting.
      */
@@ -1295,9 +1350,9 @@ var SPAPSClient = class _SPAPSClient {
       const res = await this.client.post("/api/stripe/products/with-price", payload, { headers: { Authorization: `Bearer ${this.accessToken}` } });
       return this.unwrapApiResponse(res, "Failed to create product with price");
     },
-    createProductWithPriceSuperAdmin: async (productId, payload) => {
+    createProductWithPriceSuperAdmin: async (applicationId, payload) => {
       if (!this.accessToken) throw new Error("Authentication required. Please authenticate first.");
-      const res = await this.client.post(`/api/stripe/products/super-admin/${productId}/with-price`, payload, { headers: { Authorization: `Bearer ${this.accessToken}` } });
+      const res = await this.client.post(`/api/stripe/products/super-admin/${applicationId}/with-price`, payload, { headers: { Authorization: `Bearer ${this.accessToken}` } });
       return this.unwrapApiResponse(res, "Failed to create product with price (super admin)");
     },
     setDefaultPrice: async (productId, payload) => {
@@ -1617,29 +1672,96 @@ var SPAPSClient = class _SPAPSClient {
       return this.unwrapApiResponse(res, "Failed to get checkout status");
     }
   };
+  /**
+   * Server-side usage control.
+   *
+   * These endpoints require a secret SPAPS key. Browser clients should call
+   * their own backend, then the backend should authorize before work and record
+   * after work completes.
+   */
+  usage = {
+    /**
+     * List active usage feature definitions for this application.
+     */
+    listFeatures: async () => {
+      const res = await this.client.get("/api/usage/features");
+      return this.unwrapApiResponse(res, "Failed to list usage features");
+    },
+    /**
+     * Fetch current window usage status without creating an authorization.
+     */
+    getStatus: async (query) => {
+      const q = new URLSearchParams();
+      q.set("feature_key", query.feature_key);
+      q.set("resource_type", query.resource_type);
+      if (query.resource_id) q.set("resource_id", query.resource_id);
+      if (query.subject_user_id) q.set("subject_user_id", query.subject_user_id);
+      const res = await this.client.get(`/api/usage/status?${q.toString()}`);
+      return this.unwrapApiResponse(res, "Failed to get usage status");
+    },
+    /**
+     * Authorize proposed usage before a downstream job, inference, or action runs.
+     */
+    authorize: async (payload) => {
+      const res = await this.client.post("/api/usage/authorize", payload);
+      return this.unwrapApiResponse(res, "Failed to authorize usage");
+    },
+    /**
+     * Record immutable usage after work completes.
+     */
+    record: async (payload) => {
+      const res = await this.client.post("/api/usage/record", payload);
+      return this.unwrapApiResponse(res, "Failed to record usage");
+    },
+    /**
+     * List usage events in deterministic newest-first order.
+     */
+    listHistory: async (query = {}) => {
+      const q = new URLSearchParams();
+      if (query.feature_key) q.set("feature_key", query.feature_key);
+      if (query.resource_type) q.set("resource_type", query.resource_type);
+      if (query.resource_id) q.set("resource_id", query.resource_id);
+      if (query.subject_user_id) q.set("subject_user_id", query.subject_user_id);
+      if (query.limit) q.set("limit", String(query.limit));
+      if (typeof query.offset === "number") q.set("offset", String(query.offset));
+      const suffix = q.toString() ? `?${q.toString()}` : "";
+      const res = await this.client.get(`/api/usage/history${suffix}`);
+      return this.unwrapApiResponse(res, "Failed to list usage history");
+    }
+  };
   // Stripe Methods
   async createCheckoutSession(priceId, successUrl, cancelUrl) {
-    return this.client.post("/api/stripe/create-checkout-session", {
-      price_id: priceId,
+    return this.client.post("/api/stripe/checkout-sessions", {
+      mode: "payment",
+      line_items: [{ price_id: priceId, quantity: 1 }],
       success_url: successUrl,
-      cancel_url: cancelUrl
+      cancel_url: cancelUrl ?? successUrl
     });
   }
-  async getSubscription() {
-    return this.client.get("/api/stripe/subscription");
+  async getSubscription(subscriptionId) {
+    if (subscriptionId) {
+      return this.client.get(`/api/stripe/subscription/${subscriptionId}`);
+    }
+    return this.client.get("/api/stripe/subscriptions");
   }
-  async cancelSubscription() {
-    await this.client.delete("/api/stripe/subscription");
+  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);
   }
   // Usage Methods
-  async getUsageBalance() {
-    return this.client.get("/api/usage/balance");
+  async authorizeUsage(payload) {
+    return this.usage.authorize(payload);
   }
-  async recordUsage(feature, amount) {
-    await this.client.post("/api/usage/record", {
-      feature,
-      amount
-    });
+  async recordUsage(payload) {
+    return this.usage.record(payload);
+  }
+  async getUsageStatus(query) {
+    return this.usage.getStatus(query);
+  }
+  async listUsageHistory(query = {}) {
+    return this.usage.listHistory(query);
   }
   // Secure Messaging Methods
   async createSecureMessage(payload) {

package/dist/index.mjs

@@ -722,6 +722,61 @@ var SPAPSClient = class _SPAPSClient {
       );
       return this.unwrapApiResponse(res, "Failed to create issue report");
     },
+    /**
+     * Upload one private pending screenshot attachment.
+     */
+    uploadAttachment: async (file, options) => {
+      if (typeof FormData === "undefined") {
+        throw new Error("FormData is required to upload issue report attachments");
+      }
+      const formData = new FormData();
+      const fileWithOptionalName = file;
+      const inferredFilename = typeof fileWithOptionalName.name === "string" ? fileWithOptionalName.name : void 0;
+      const filename = options?.filename ?? inferredFilename;
+      if (filename) {
+        formData.append("file", file, filename);
+      } else {
+        formData.append("file", file);
+      }
+      const res = await this.client.post(
+        "/api/v1/issue-reports/attachments",
+        formData,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      return this.unwrapApiResponse(res, "Failed to upload issue report attachment");
+    },
+    /**
+     * List non-deleted screenshot attachments for one issue report.
+     */
+    listAttachments: async (issueReportId) => {
+      const res = await this.client.get(
+        `/api/v1/issue-reports/${encodeURIComponent(issueReportId)}/attachments`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      return this.unwrapApiResponse(res, "Failed to list issue report attachments");
+    },
+    /**
+     * Return a short-lived private attachment access URL.
+     */
+    getAttachmentAccessUrl: async (attachmentId) => {
+      const res = await this.client.get(
+        `/api/v1/issue-reports/attachments/${encodeURIComponent(attachmentId)}/access`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to get issue report attachment access URL"
+      );
+    },
+    /**
+     * Soft-delete one owned screenshot attachment.
+     */
+    deleteAttachment: async (attachmentId) => {
+      await this.client.delete(
+        `/api/v1/issue-reports/attachments/${encodeURIComponent(attachmentId)}`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+    },
     /**
      * Create a short-lived voice transcription token for issue reporting.
      */
@@ -1260,9 +1315,9 @@ var SPAPSClient = class _SPAPSClient {
       const res = await this.client.post("/api/stripe/products/with-price", payload, { headers: { Authorization: `Bearer ${this.accessToken}` } });
       return this.unwrapApiResponse(res, "Failed to create product with price");
     },
-    createProductWithPriceSuperAdmin: async (productId, payload) => {
+    createProductWithPriceSuperAdmin: async (applicationId, payload) => {
       if (!this.accessToken) throw new Error("Authentication required. Please authenticate first.");
-      const res = await this.client.post(`/api/stripe/products/super-admin/${productId}/with-price`, payload, { headers: { Authorization: `Bearer ${this.accessToken}` } });
+      const res = await this.client.post(`/api/stripe/products/super-admin/${applicationId}/with-price`, payload, { headers: { Authorization: `Bearer ${this.accessToken}` } });
       return this.unwrapApiResponse(res, "Failed to create product with price (super admin)");
     },
     setDefaultPrice: async (productId, payload) => {
@@ -1582,29 +1637,96 @@ var SPAPSClient = class _SPAPSClient {
       return this.unwrapApiResponse(res, "Failed to get checkout status");
     }
   };
+  /**
+   * Server-side usage control.
+   *
+   * These endpoints require a secret SPAPS key. Browser clients should call
+   * their own backend, then the backend should authorize before work and record
+   * after work completes.
+   */
+  usage = {
+    /**
+     * List active usage feature definitions for this application.
+     */
+    listFeatures: async () => {
+      const res = await this.client.get("/api/usage/features");
+      return this.unwrapApiResponse(res, "Failed to list usage features");
+    },
+    /**
+     * Fetch current window usage status without creating an authorization.
+     */
+    getStatus: async (query) => {
+      const q = new URLSearchParams();
+      q.set("feature_key", query.feature_key);
+      q.set("resource_type", query.resource_type);
+      if (query.resource_id) q.set("resource_id", query.resource_id);
+      if (query.subject_user_id) q.set("subject_user_id", query.subject_user_id);
+      const res = await this.client.get(`/api/usage/status?${q.toString()}`);
+      return this.unwrapApiResponse(res, "Failed to get usage status");
+    },
+    /**
+     * Authorize proposed usage before a downstream job, inference, or action runs.
+     */
+    authorize: async (payload) => {
+      const res = await this.client.post("/api/usage/authorize", payload);
+      return this.unwrapApiResponse(res, "Failed to authorize usage");
+    },
+    /**
+     * Record immutable usage after work completes.
+     */
+    record: async (payload) => {
+      const res = await this.client.post("/api/usage/record", payload);
+      return this.unwrapApiResponse(res, "Failed to record usage");
+    },
+    /**
+     * List usage events in deterministic newest-first order.
+     */
+    listHistory: async (query = {}) => {
+      const q = new URLSearchParams();
+      if (query.feature_key) q.set("feature_key", query.feature_key);
+      if (query.resource_type) q.set("resource_type", query.resource_type);
+      if (query.resource_id) q.set("resource_id", query.resource_id);
+      if (query.subject_user_id) q.set("subject_user_id", query.subject_user_id);
+      if (query.limit) q.set("limit", String(query.limit));
+      if (typeof query.offset === "number") q.set("offset", String(query.offset));
+      const suffix = q.toString() ? `?${q.toString()}` : "";
+      const res = await this.client.get(`/api/usage/history${suffix}`);
+      return this.unwrapApiResponse(res, "Failed to list usage history");
+    }
+  };
   // Stripe Methods
   async createCheckoutSession(priceId, successUrl, cancelUrl) {
-    return this.client.post("/api/stripe/create-checkout-session", {
-      price_id: priceId,
+    return this.client.post("/api/stripe/checkout-sessions", {
+      mode: "payment",
+      line_items: [{ price_id: priceId, quantity: 1 }],
       success_url: successUrl,
-      cancel_url: cancelUrl
+      cancel_url: cancelUrl ?? successUrl
     });
   }
-  async getSubscription() {
-    return this.client.get("/api/stripe/subscription");
+  async getSubscription(subscriptionId) {
+    if (subscriptionId) {
+      return this.client.get(`/api/stripe/subscription/${subscriptionId}`);
+    }
+    return this.client.get("/api/stripe/subscriptions");
   }
-  async cancelSubscription() {
-    await this.client.delete("/api/stripe/subscription");
+  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);
   }
   // Usage Methods
-  async getUsageBalance() {
-    return this.client.get("/api/usage/balance");
+  async authorizeUsage(payload) {
+    return this.usage.authorize(payload);
   }
-  async recordUsage(feature, amount) {
-    await this.client.post("/api/usage/record", {
-      feature,
-      amount
-    });
+  async recordUsage(payload) {
+    return this.usage.record(payload);
+  }
+  async getUsageStatus(query) {
+    return this.usage.getStatus(query);
+  }
+  async listUsageHistory(query = {}) {
+    return this.usage.listHistory(query);
   }
   // Secure Messaging Methods
   async createSecureMessage(payload) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps-sdk",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "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.2.0"
+    "spaps-types": "^1.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",