spaps-sdk 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -6,6 +6,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-05-11
+
+- Maintenance: align the SDK package version after release automation.
+
 ## [1.7.0] - 2026-05-09
 
 - Added `dayrate.getCheckoutStatus(sessionId)` and checkout-status response types for Bookme/dayrate confirmation polling.

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` |
@@ -88,6 +88,7 @@ Relevant environment variables:
 | `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 |
@@ -144,6 +145,56 @@ 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,
+  },
+});
+```
+
+The legacy `/api/usage/features` and `/api/usage/history` routes remain
+not-implemented stubs and are not exposed through this SDK namespace.
+
 ### 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 +416,7 @@ npm run test:readme
 ## Metadata
 
 - `package_name`: `spaps-sdk`
-- `latest_version`: `1.7.0`
+- `latest_version`: `1.8.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, createSecureMessageRequestSchema, isX402PaymentRequired, isX402ResourceStatus, 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, 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';
 
 /**
  * Permission checking utilities for SPAPS SDK
@@ -1091,6 +1091,23 @@ 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: {
+        /**
+         * 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>;
+    };
     createCheckoutSession(priceId: string, successUrl: string, cancelUrl?: string): Promise<{
         data: CheckoutSession;
     }>;
@@ -1098,10 +1115,8 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
         data: Subscription;
     }>;
     cancelSubscription(): Promise<void>;
-    getUsageBalance(): Promise<{
-        data: UsageBalance;
-    }>;
-    recordUsage(feature: string, amount: number): Promise<void>;
+    authorizeUsage(payload: UsageControlAuthorizeRequest): Promise<UsageControlAuthorizeResponse>;
+    recordUsage(payload: UsageControlRecordRequest): Promise<UsageControlRecordResponse>;
     private createSecureMessage;
     private listSecureMessages;
     /**

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, createSecureMessageRequestSchema, isX402PaymentRequired, isX402ResourceStatus, 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, 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';
 
 /**
  * Permission checking utilities for SPAPS SDK
@@ -1091,6 +1091,23 @@ 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: {
+        /**
+         * 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>;
+    };
     createCheckoutSession(priceId: string, successUrl: string, cancelUrl?: string): Promise<{
         data: CheckoutSession;
     }>;
@@ -1098,10 +1115,8 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
         data: Subscription;
     }>;
     cancelSubscription(): Promise<void>;
-    getUsageBalance(): Promise<{
-        data: UsageBalance;
-    }>;
-    recordUsage(feature: string, amount: number): Promise<void>;
+    authorizeUsage(payload: UsageControlAuthorizeRequest): Promise<UsageControlAuthorizeResponse>;
+    recordUsage(payload: UsageControlRecordRequest): Promise<UsageControlRecordResponse>;
     private createSecureMessage;
     private listSecureMessages;
     /**

package/dist/index.js

@@ -204,6 +204,7 @@ __export(index_exports, {
   WalletUtils: () => WalletUtils,
   WebSocketAuthHelper: () => WebSocketAuthHelper,
   X402PaymentRequiredSDKError: () => X402PaymentRequiredSDKError,
+  atomicToMoneyUnits: () => import_spaps_types.atomicToMoneyUnits,
   canAccessAdmin: () => canAccessAdmin,
   createBrowserClient: () => createBrowserClient,
   createPermissionChecker: () => createPermissionChecker,
@@ -222,10 +223,13 @@ __export(index_exports, {
   isSuccessEnvelope: () => isSuccessEnvelope,
   isX402PaymentRequired: () => import_spaps_types.isX402PaymentRequired,
   isX402ResourceStatus: () => import_spaps_types.isX402ResourceStatus,
+  moneyUnitsToAtomic: () => import_spaps_types.moneyUnitsToAtomic,
+  roundHalfToPositiveInfinity: () => import_spaps_types.roundHalfToPositiveInfinity,
   secureMessageMetadataSchema: () => import_spaps_types2.secureMessageMetadataSchema,
   secureMessageSchema: () => import_spaps_types2.secureMessageSchema,
   unwrapEnvelope: () => unwrapEnvelope,
   unwrapNestedData: () => unwrapNestedData,
+  validatePositiveAmountAtomic: () => import_spaps_types.validatePositiveAmountAtomic,
   verifyCryptoWebhookSignature: () => verifyCryptoWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
@@ -1613,6 +1617,29 @@ 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 = {
+    /**
+     * 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");
+    }
+  };
   // Stripe Methods
   async createCheckoutSession(priceId, successUrl, cancelUrl) {
     return this.client.post("/api/stripe/create-checkout-session", {
@@ -1628,14 +1655,11 @@ var SPAPSClient = class _SPAPSClient {
     await this.client.delete("/api/stripe/subscription");
   }
   // 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);
   }
   // Secure Messaging Methods
   async createSecureMessage(payload) {
@@ -2099,6 +2123,7 @@ function detectKeyType(key) {
   WalletUtils,
   WebSocketAuthHelper,
   X402PaymentRequiredSDKError,
+  atomicToMoneyUnits,
   canAccessAdmin,
   createBrowserClient,
   createPermissionChecker,
@@ -2116,9 +2141,12 @@ function detectKeyType(key) {
   isSuccessEnvelope,
   isX402PaymentRequired,
   isX402ResourceStatus,
+  moneyUnitsToAtomic,
+  roundHalfToPositiveInfinity,
   secureMessageMetadataSchema,
   secureMessageSchema,
   unwrapEnvelope,
   unwrapNestedData,
+  validatePositiveAmountAtomic,
   verifyCryptoWebhookSignature
 });

package/dist/index.mjs

@@ -192,7 +192,11 @@ import crypto from "crypto";
 import axios from "axios";
 import {
   isX402PaymentRequired,
-  isX402ResourceStatus
+  isX402ResourceStatus,
+  atomicToMoneyUnits,
+  moneyUnitsToAtomic,
+  roundHalfToPositiveInfinity,
+  validatePositiveAmountAtomic
 } from "spaps-types";
 import {
   createSecureMessageRequestSchema,
@@ -1578,6 +1582,29 @@ 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 = {
+    /**
+     * 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");
+    }
+  };
   // Stripe Methods
   async createCheckoutSession(priceId, successUrl, cancelUrl) {
     return this.client.post("/api/stripe/create-checkout-session", {
@@ -1593,14 +1620,11 @@ var SPAPSClient = class _SPAPSClient {
     await this.client.delete("/api/stripe/subscription");
   }
   // 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);
   }
   // Secure Messaging Methods
   async createSecureMessage(payload) {
@@ -2063,6 +2087,7 @@ export {
   WalletUtils,
   WebSocketAuthHelper,
   X402PaymentRequiredSDKError,
+  atomicToMoneyUnits,
   canAccessAdmin,
   createBrowserClient,
   createPermissionChecker,
@@ -2081,9 +2106,12 @@ export {
   isSuccessEnvelope,
   isX402PaymentRequired,
   isX402ResourceStatus,
+  moneyUnitsToAtomic,
+  roundHalfToPositiveInfinity,
   secureMessageMetadataSchema,
   secureMessageSchema,
   unwrapEnvelope,
   unwrapNestedData,
+  validatePositiveAmountAtomic,
   verifyCryptoWebhookSignature
 };

package/package.json

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