spaps-sdk 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+- No changes yet.
+
+## [1.6.1] - 2026-02-16
+
+### Fixed
+
+- Made the SDK `tsconfig` self-contained after root-config removal.
+- Restored API-key header injection behavior for axios v1+ interceptor semantics.
+
+## [1.6.0] - 2026-02-14
+
+### Added
+
+- CFO roles, `company_id`, and affiliate-referral domain support.
+
+### Changed
+
+- Consolidated SPAPS integration patterns into published SDK packages.
+
+## [1.5.1] - 2026-02-11
+
+### Changed
+
+- Standardized local/dev config defaults, including port `3301`.
+
+## [1.5.0] - 2026-01-10
+
+### Added
+
+- Set-password endpoint support for authenticated users.
+
+## [1.4.0] - 2026-01-10
+
+### Added
+
+- Email service integration with Mailgun support.
+
+## [1.2.1] - 2025-12-31
+
+### Added
+
+- Stripe webhook admin tooling for entitlement operations.
+- CFO auth integration helpers.
+
+## [1.1.52] - 2025-10-15
+
+### Fixed
+
+- Build and type-export stability across iterative CI packaging fixes.
+
+## [1.1.0] - 2025-10-12
+
+### Added
+
+- Admin API methods for Stripe product/price management and sync flows.
+- Built-in permission utilities: `isAdminAccount`, `canAccessAdmin`, `getUserRole`.
+
+### Changed
+
+- Subsequent patch iterations through `1.1.52` focused on CI and type-export stabilization.
+
+## [1.0.0] - 2025-10-08
+
+### Added
+
+- Initial npm release as `spaps-sdk`.
+- Zero-config client for SPAPS auth, payments, and permission checks.
+- Local-mode auto-detection (`localhost`/`127.0.0.1`).
+- Email/password, wallet, and magic-link authentication flows.
+- Stripe checkout helpers with legal-consent support.
+- Usage tracking and secure messaging helpers.
+- TypeScript definitions with CJS/ESM dual exports.
+- Node/browser/Next.js/React Native compatibility.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sweet Potato Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PERMISSIONS.md

@@ -0,0 +1,390 @@
+# 🔐 SPAPS SDK Permission Utilities
+
+Client-side permission checking and role management utilities for SPAPS applications.
+
+## 🚀 Quick Start
+
+```typescript
+import { 
+  isAdminAccount, 
+  getUserRole, 
+  hasPermission, 
+  canAccessAdmin,
+  PermissionChecker,
+  createPermissionChecker 
+} from 'spaps-sdk';
+
+// Check if user is admin
+const isAdmin = isAdminAccount('buildooor@gmail.com'); // true
+
+// Get user role
+const role = getUserRole('user@example.com'); // 'user' | 'admin' | 'guest'
+
+// Check admin access
+const adminCheck = canAccessAdmin(user);
+if (adminCheck.allowed) {
+  // Show admin features
+}
+
+// Check specific permissions
+const canEdit = hasPermission(user, 'edit');
+const canManage = hasPermission(user, ['create', 'delete']);
+```
+
+## 📋 Default Admin Accounts
+
+```typescript
+const DEFAULT_ADMIN_ACCOUNTS = {
+  email: 'buildooor@gmail.com',
+  wallets: {
+    ethereum: '0xa72bb7CeF1e4B2Cc144373d8dE0Add7CCc8DF4Ba',
+    solana: 'HVEbdiYU3Rr34NHBSgKs7q8cvdTeZLqNL77Z1FB2vjLy'
+  }
+};
+```
+
+## 🎯 React Component Examples
+
+### Admin Button with Permission Checking
+
+```tsx
+import React from 'react';
+import { canAccessAdmin, getUserDisplay } from 'spaps-sdk';
+
+interface AdminButtonProps {
+  user: User | null;
+  onClick: () => void;
+}
+
+export function AdminButton({ user, onClick }: AdminButtonProps) {
+  const permissionCheck = canAccessAdmin(user);
+  const userDisplay = getUserDisplay(user);
+
+  if (!permissionCheck.allowed) {
+    return (
+      <button 
+        disabled 
+        title={permissionCheck.reason}
+        className="btn-disabled"
+      >
+        Admin Panel
+      </button>
+    );
+  }
+
+  return (
+    <button onClick={onClick} className="btn-primary">
+      {userDisplay.badge} Admin Panel
+    </button>
+  );
+}
+```
+
+### Protected Route Component
+
+```tsx
+import React from 'react';
+import { canAccessAdmin, getRoleAwareErrorMessage } from 'spaps-sdk';
+
+interface ProtectedRouteProps {
+  user: User | null;
+  children: React.ReactNode;
+}
+
+export function AdminRoute({ user, children }: ProtectedRouteProps) {
+  const permissionCheck = canAccessAdmin(user);
+
+  if (!permissionCheck.allowed) {
+    const errorMessage = getRoleAwareErrorMessage(
+      'admin',
+      permissionCheck.userRole,
+      'access this page'
+    );
+
+    return (
+      <div className="error-container">
+        <h2>Access Denied</h2>
+        <p>{errorMessage}</p>
+      </div>
+    );
+  }
+
+  return <>{children}</>;
+}
+```
+
+### User Display with Role Badge
+
+```tsx
+import React from 'react';
+import { getUserDisplay } from 'spaps-sdk';
+
+export function UserProfile({ user }: { user: User | null }) {
+  const display = getUserDisplay(user);
+
+  return (
+    <div className="user-profile">
+      <span>{display.displayName}</span>
+      {display.badge && (
+        <span className="role-badge">{display.badge}</span>
+      )}
+      <span className="role-text">({display.role})</span>
+    </div>
+  );
+}
+```
+
+## 🛠️ Advanced Usage
+
+### Custom Permission Checker
+
+```typescript
+import { createPermissionChecker } from 'spaps-sdk';
+
+// Create checker with custom admin accounts
+const customAdmins = [
+  'admin@mycompany.com',
+  '0x1234567890abcdef...',
+  {
+    email: 'ceo@company.com',
+    wallets: {
+      ethereum: '0xabcdef...',
+      solana: 'ABC123...'
+    }
+  }
+];
+
+const checker = createPermissionChecker(customAdmins);
+
+// Use the checker
+const isAdmin = checker.isAdmin('admin@mycompany.com'); // true
+const userDisplay = checker.getUserDisplay(user);
+const canAccess = checker.canAccessAdmin(user);
+```
+
+### Permission-Based UI Rendering
+
+```tsx
+import React from 'react';
+import { hasPermission, PermissionChecker } from 'spaps-sdk';
+
+const checker = new PermissionChecker();
+
+function Dashboard({ user }: { user: User | null }) {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      
+      {/* Show admin panel for admins only */}
+      {!checker.requiresAdmin(user) && (
+        <AdminPanel />
+      )}
+      
+      {/* Show billing section for users with billing permission */}
+      {hasPermission(user, 'billing') && (
+        <BillingSection />
+      )}
+      
+      {/* Show different content based on role */}
+      {checker.getRole(user?.email) === 'admin' ? (
+        <AdminDashboard />
+      ) : (
+        <UserDashboard />
+      )}
+    </div>
+  );
+}
+```
+
+### Form with Permission Validation
+
+```tsx
+import React, { useState } from 'react';
+import { hasPermission, getRoleAwareErrorMessage } from 'spaps-sdk';
+
+function ProductForm({ user }: { user: User | null }) {
+  const [product, setProduct] = useState({ name: '', price: '' });
+  const canCreate = hasPermission(user, 'create');
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    if (!canCreate) {
+      const errorMessage = getRoleAwareErrorMessage(
+        'permission',
+        user ? 'user' : 'guest',
+        'create products'
+      );
+      alert(errorMessage);
+      return;
+    }
+    
+    // Submit product
+    createProduct(product);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={product.name}
+        onChange={(e) => setProduct({ ...product, name: e.target.value })}
+        placeholder="Product name"
+      />
+      <input
+        value={product.price}
+        onChange={(e) => setProduct({ ...product, price: e.target.value })}
+        placeholder="Price"
+      />
+      <button 
+        type="submit" 
+        disabled={!canCreate}
+        title={!canCreate ? 'Insufficient permissions' : undefined}
+      >
+        {canCreate ? 'Create Product' : 'Create Product (No Permission)'}
+      </button>
+    </form>
+  );
+}
+```
+
+## 🧪 Testing Examples
+
+```typescript
+import { 
+  isAdminAccount, 
+  getUserRole, 
+  canAccessAdmin,
+  createPermissionChecker 
+} from 'spaps-sdk';
+
+describe('Permission Utilities', () => {
+  describe('isAdminAccount', () => {
+    it('should recognize default admin accounts', () => {
+      expect(isAdminAccount('buildooor@gmail.com')).toBe(true);
+      expect(isAdminAccount('0xa72bb7CeF1e4B2Cc144373d8dE0Add7CCc8DF4Ba')).toBe(true);
+      expect(isAdminAccount('user@example.com')).toBe(false);
+    });
+
+    it('should recognize custom admin accounts', () => {
+      const customAdmins = ['admin@test.com'];
+      expect(isAdminAccount('admin@test.com', customAdmins)).toBe(true);
+      expect(isAdminAccount('user@test.com', customAdmins)).toBe(false);
+    });
+  });
+
+  describe('getUserRole', () => {
+    it('should return correct roles', () => {
+      expect(getUserRole('buildooor@gmail.com')).toBe('admin');
+      expect(getUserRole('user@example.com')).toBe('user');
+      expect(getUserRole()).toBe('guest');
+    });
+  });
+
+  describe('canAccessAdmin', () => {
+    it('should check admin access correctly', () => {
+      const adminUser = { id: '1', email: 'buildooor@gmail.com' };
+      const regularUser = { id: '2', email: 'user@example.com' };
+
+      expect(canAccessAdmin(adminUser).allowed).toBe(true);
+      expect(canAccessAdmin(regularUser).allowed).toBe(false);
+      expect(canAccessAdmin(null).allowed).toBe(false);
+    });
+  });
+
+  describe('PermissionChecker', () => {
+    it('should work with custom admins', () => {
+      const checker = createPermissionChecker(['admin@test.com']);
+      
+      expect(checker.isAdmin('admin@test.com')).toBe(true);
+      expect(checker.getRole('admin@test.com')).toBe('admin');
+      expect(checker.canAccessAdmin({ 
+        id: '1', 
+        email: 'admin@test.com' 
+      }).allowed).toBe(true);
+    });
+  });
+});
+```
+
+## 📚 API Reference
+
+### Core Functions
+
+#### `isAdminAccount(identifier: string, customAdmins?: AdminConfig[]): boolean`
+Check if an identifier (email/wallet) is an admin account.
+
+#### `getUserRole(identifier?: string, customAdmins?: AdminConfig[]): string`
+Get user role: 'admin', 'user', or 'guest'.
+
+#### `hasPermission(user: User | null, permissions: string | string[], customAdmins?: AdminConfig[]): boolean`
+Check if user has specific permissions.
+
+#### `canAccessAdmin(user: User | null, customAdmins?: AdminConfig[]): PermissionCheckResult`
+Check if user can access admin features.
+
+#### `getRoleAwareErrorMessage(requiredRole: string, userRole: string, action?: string): string`
+Get contextual error message based on roles.
+
+#### `getUserDisplay(user: User | null, customAdmins?: AdminConfig[])`
+Get user display information with role indicators.
+
+### PermissionChecker Class
+
+```typescript
+class PermissionChecker {
+  constructor(customAdmins?: AdminConfig[]);
+  
+  isAdmin(identifier: string): boolean;
+  getRole(identifier?: string): string;
+  hasPermission(user: User | null, permissions: string | string[]): boolean;
+  canAccessAdmin(user: User | null): PermissionCheckResult;
+  getErrorMessage(requiredRole: string, userRole: string, action?: string): string;
+  getUserDisplay(user: User | null);
+  
+  // Convenience methods
+  requiresAuth(user: User | null): boolean;
+  requiresAdmin(user: User | null): boolean;
+  
+  // Admin management
+  addCustomAdmin(admin: string | AdminConfig): void;
+  removeCustomAdmin(admin: string | AdminConfig): void;
+}
+```
+
+### Interfaces
+
+```typescript
+interface User {
+  id: string;
+  email?: string;
+  wallet_address?: string;
+  role?: string;
+  permissions?: string[];
+  tier?: string;
+}
+
+interface AdminConfig {
+  email: string;
+  wallets: {
+    ethereum: string;
+    solana: string;
+  };
+}
+
+interface PermissionCheckResult {
+  allowed: boolean;
+  reason?: string;
+  userRole: string;
+  requiredRole?: string;
+}
+```
+
+## 🌟 Best Practices
+
+1. **Server-side validation**: Always validate permissions on the server
+2. **Progressive enhancement**: Use client-side checks for UX, not security
+3. **Consistent error messages**: Use `getRoleAwareErrorMessage` for user-friendly errors
+4. **Role-based UI**: Show/hide features based on user permissions
+5. **Custom admin management**: Use custom admin lists for multi-tenant apps
+6. **Testing**: Test permission logic with various user states
+7. **Type safety**: Use TypeScript interfaces for better development experience

package/README.md

@@ -1,19 +1,4 @@
----
-id: spaps-typescript-sdk
-title: spaps TypeScript SDK
-category: sdk
-tags:
-  - sdk
-  - typescript
-  - client
-ai_summary: |
-  Reference for the spaps TypeScript SDK covering configuration, admin helpers,
-  and examples for interacting with authentication, payments, and permission
-  APIs from JavaScript or TypeScript applications.
-last_updated: 2025-02-14
----
-
-# @spaps/sdk
+# spaps-sdk
 
 <a href="https://www.npmjs.com/package/spaps-sdk"><img alt="npm" src="https://img.shields.io/npm/v/spaps-sdk.svg"></a>
 <img alt="node" src="https://img.shields.io/badge/node-%3E%3D14-brightgreen">
@@ -21,71 +6,21 @@ last_updated: 2025-02-14
 
 > Sweet Potato Authentication & Payment Service SDK
 
-Zero-config client for SPAPS authentication, payments, and permission checking. Works automatically with local development mode.
+Zero-config client for SPAPS authentication, payments, secure messaging, and admin/product workflows.
 
-## 🔐 New in v1.1.0: Admin API Methods!
+## Quick Facts
 
-Built-in admin API methods for Stripe product management:
+- Package: `spaps-sdk`
+- Latest version: `1.6.1`
+- Runtime: `Node.js >=14.0.0`
+- Default local API URL: `http://localhost:3301`
 
-```typescript
-import { SPAPSClient } from 'spaps-sdk';
-
-const spaps = new SPAPSClient({
-  apiKey: 'your-api-key',
-  apiUrl: 'https://api.sweetpotato.dev'
-});
+## Metadata
 
-// Authenticate as admin
-await spaps.signIn('admin@example.com', 'password');
-
-// Admin API methods
-await spaps.admin.createProduct({
-  name: 'Premium Plan',
-  category: 'subscription',
-  description: 'Advanced features'
-});
-
-await spaps.admin.updateProduct('prod_123', {
-  name: 'Premium Plan Pro'
-});
-
-await spaps.admin.createPrice({
-  product_id: 'prod_123',
-  unit_amount: 2999,
-  currency: 'usd',
-  interval: 'month'
-});
-
-// Super admin operations
-await spaps.admin.syncProducts();
-```
-
-## 🔐 Permission Utilities
-
-Built-in permission checking and role-based access control:
-
-```typescript
-import { isAdminAccount, canAccessAdmin, getUserRole } from 'spaps-sdk';
-
-// Check admin status
-const isAdmin = isAdminAccount('buildooor@gmail.com'); // true
-
-// Check admin access with detailed result
-const adminCheck = canAccessAdmin(user);
-if (adminCheck.allowed) {
-  // Show admin UI
-}
-
-// Get user role
-const role = getUserRole('user@example.com'); // 'user' | 'admin' | 'guest'
-
-// Check if authenticated user is admin
-if (spaps.isAdmin(currentUser)) {
-  // Show admin features
-}
-```
-
-See [PERMISSIONS.md](./PERMISSIONS.md) for React examples and complete documentation.
+- `package_name`: `spaps-sdk`
+- `latest_version`: `1.6.1`
+- `minimum_runtime`: `Node.js >=14.0.0`
+- `api_base_url`: `https://api.sweetpotato.dev`
 
 ## Installation
 
@@ -97,349 +32,153 @@ yarn add spaps-sdk
 pnpm add spaps-sdk
 ```
 
-### Compatibility
-
-- ✅ **Node.js**: Fully supported (v14+) with automatic fetch polyfill
-- ✅ **Browser**: Works in all modern browsers  
-- ✅ **TypeScript**: Full type definitions included
-- ✅ **Next.js**: Server and client components supported
-- ✅ **React Native**: Compatible with proper setup
-
-The SDK automatically includes a `cross-fetch` polyfill for Node.js environments that don't have native fetch support.
-
 ## Quick Start
 
-```javascript
+```typescript
 import { SPAPSClient } from 'spaps-sdk';
-// or
-const { SPAPSClient } = require('spaps-sdk');
 
-// Auto-detects local mode - no API key needed for localhost!
 const spaps = new SPAPSClient({
-  apiUrl: 'http://localhost:3301' // Optional, auto-detected
+  apiUrl: 'http://localhost:3301',
 });
 
-// Login
 const { data } = await spaps.login('user@example.com', 'password');
 console.log('User:', data.user);
 
-// Check authentication
 if (spaps.isAuthenticated()) {
-  const user = await spaps.getUser();
-  console.log('Current user:', user.data);
+  const me = await spaps.getUser();
+  console.log(me.data.email);
 }
 ```
 
-## Local Mode Explained
-
-- If `apiUrl` is omitted or points to `localhost`/`127.0.0.1`, the SDK runs in local mode.
-- Local mode integrates seamlessly with the `spaps` CLI (`npx spaps local`), defaulting to `http://localhost:3301`.
-- No API key is required in local mode; tokens and data are managed locally for development.
+## Compatibility
 
-You can check the mode at runtime:
-
-```ts
-spaps.isLocalMode(); // true | false
-```
+- Node.js (v14+)
+- Modern browsers
+- TypeScript (types bundled)
+- Next.js and React Native
 
-## Environment Variables
+The SDK includes a `cross-fetch` polyfill for Node environments without native fetch.
 
-The SDK can read configuration from environment variables (useful in Next.js and Node):
+## Configuration
 
-- `SPAPS_API_URL` or `NEXT_PUBLIC_SPAPS_API_URL` — API base URL
-- `SPAPS_API_KEY` — API key for production use
+`SPAPSClient` reads config from constructor args first, then environment variables.
 
-Example (Node):
+- `SPAPS_API_URL` or `NEXT_PUBLIC_SPAPS_API_URL` - API base URL
+- `SPAPS_API_KEY` or `NEXT_PUBLIC_SPAPS_API_KEY` - API key
 
 ```bash
+# Node
 export SPAPS_API_URL=https://api.sweetpotato.dev
 export SPAPS_API_KEY=spaps_xxx
-```
 
-Example (Next.js):
-
-```env
+# Next.js
 NEXT_PUBLIC_SPAPS_API_URL=https://api.sweetpotato.dev
 ```
 
-## Features
+Local mode auto-detection:
 
-### 🚀 Zero Configuration
-- **Auto-detects local mode** - No API key needed for localhost
-- **Auto-refreshes tokens** - Handles expired tokens automatically
-- **TypeScript support** - Full type definitions included
-- **Crypto payments ready** - Create invoices, poll status, verify webhooks, trigger reconciliation
+- If `apiUrl` is omitted or points to `localhost`/`127.0.0.1`, local mode is enabled.
+- In local mode, API key is optional.
 
-### 🔐 Authentication Methods
-```javascript
-// Email/Password
-await spaps.login(email, password);
-await spaps.register(email, password);
+## API Surface
 
-// Wallet Authentication
-await spaps.walletSignIn(walletAddress, signature, message, 'solana');
+- `auth` and top-level auth helpers: password, wallet, magic link, refresh/logout
+- `sessions`: current/list/validate/revoke/touch
+- `payments`: checkout sessions, products/prices, guest checkout, subscriptions, crypto invoices
+- `secureMessages`: create/list secure messages
+- `email`: send/list templates/get template/preview template
+- `entitlements`: list/check/list by resource
+- `admin`: product and price management helpers
+- `dayrate`, `cfo`: specialized domain helpers
 
-// Token Management
-await spaps.refresh();
-await spaps.logout();
-
-// Get User
-const user = await spaps.getUser();
-```
-
-### 💳 Stripe Integration
-```javascript
-// Create checkout session with consent control
-const session = await spaps.payments.createPaymentCheckout({
-  price_id: 'price_123',
-  success_url: 'https://app.example.com/success',
-  cancel_url: 'https://app.example.com/cancel',
-  require_legal_consent: true,
-  legal_consent_text: 'I agree I am 18+ and accept the HTMA Terms & Privacy.'
-});
-window.location.href = session.url;
+## Permission Utilities
 
-// Manage subscription
-const subscription = await spaps.getSubscription();
-await spaps.cancelSubscription();
-```
-> `require_legal_consent` forces Stripe’s Terms/Privacy checkbox, and `legal_consent_text` (≤120 chars) customizes the copy. Text is sanitized and defaults to “I agree to the Terms of Service and Privacy Policy.” when omitted.
+```typescript
+import { isAdminAccount, canAccessAdmin, getUserRole } from 'spaps-sdk';
 
-### 📊 Usage Tracking
-```javascript
-// Check balance
-const balance = await spaps.getUsageBalance();
-console.log(`Credits: ${balance.data.balance}`);
+const isAdmin = isAdminAccount('buildooor@gmail.com');
+const role = getUserRole('user@example.com');
+const adminCheck = canAccessAdmin({ id: 'u1', email: 'user@example.com' });
 
-// Record usage
-await spaps.recordUsage('api-call', 1);
+if (adminCheck.allowed) {
+  // render admin UI
+}
 ```
 
-### ✉️ Secure Messaging
-```javascript
-// Create a secure message (content encrypted server-side when pii_enabled)
-const message = await spaps.secureMessages.create({
-  patientId: '3d6f0a51-8d77-4b38-8248-2d1b2f1f6c7f',
-  practitionerId: 'a3d7f431-6c9d-4cbc-9f78-4e5b6a7c8d9e',
-  content: 'Patient is experiencing intermittent headaches.',
-  metadata: { urgency: 'high' }
-});
+See [PERMISSIONS.md](./PERMISSIONS.md) for React-oriented examples.
 
-// List secure messages for the current application
-const messages = await spaps.secureMessages.list();
-console.log(messages[0].content);
-```
-> Ensure your application has `settings.pii_enabled = true` so payloads are encrypted automatically.
+## Secure Messaging
 
 ```typescript
-// Provide a strongly typed metadata shape for downstream usage
 type SecureMessageMetadata = { urgency: 'low' | 'high'; tags?: string[] };
 
-const spaps = new SPAPSClient<SecureMessageMetadata>({ apiKey: process.env.SPAPS_API_KEY });
+const spaps = new SPAPSClient<SecureMessageMetadata>({
+  apiUrl: 'https://api.sweetpotato.dev',
+  apiKey: process.env.SPAPS_API_KEY,
+});
 
 await spaps.secureMessages.create({
   patientId: '3d6f0a51-8d77-4b38-8248-2d1b2f1f6c7f',
   practitionerId: 'a3d7f431-6c9d-4cbc-9f78-4e5b6a7c8d9e',
   content: 'Follow up scheduled for next week.',
-  metadata: { urgency: 'low', tags: ['follow-up'] }
+  metadata: { urgency: 'low', tags: ['follow-up'] },
 });
-
-const typedMessages = await spaps.secureMessages.list();
-typedMessages[0].metadata.urgency; // "low" | "high"
-```
-
-Need runtime validation too? Reuse the shared schemas that ship with the SDK:
-
-```typescript
-import { z } from 'zod';
-import { createSecureMessageRequestSchema } from 'spaps-sdk';
-
-const secureMessageRequestSchema = createSecureMessageRequestSchema(
-  z.object({ urgency: z.enum(['low', 'high']), tags: z.array(z.string()).optional() })
-);
-
-secureMessageRequestSchema.parse({
-  patientId: '3d6f0a51-8d77-4b38-8248-2d1b2f1f6c7f',
-  practitionerId: 'a3d7f431-6c9d-4cbc-9f78-4e5b6a7c8d9e',
-  content: 'All clear.',
-  metadata: { urgency: 'low' }
-});
-```
-
-## Configuration
-
-### Production Mode
-```javascript
-const spaps = new SPAPSClient({
-  apiUrl: 'https://api.sweetpotato.dev',
-  apiKey: 'spaps_your_api_key_here',
-  timeout: 10000 // Optional timeout in ms
-});
-```
-
-### Local Development Mode (Auto-detected)
-```javascript
-const spaps = new SPAPSClient();
-// Automatically uses http://localhost:3301 with no API key
-```
-
-### Environment Variables
-```bash
-# .env
-SPAPS_API_URL=https://api.sweetpotato.dev
-SPAPS_API_KEY=spaps_your_api_key_here
-
-# Next.js
-NEXT_PUBLIC_SPAPS_API_URL=https://api.sweetpotato.dev
-```
-
-## Helper Methods
-
-```javascript
-// Check if authenticated
-spaps.isAuthenticated() // boolean
-
-// Get current access token
-spaps.getAccessToken() // string | undefined
-
-// Set access token manually
-spaps.setAccessToken(token)
-
-// Check if in local mode
-spaps.isLocalMode() // boolean
-
-// Health check
-await spaps.health()
-```
-
-## Types
-
-The SDK ships with full TypeScript definitions. For most apps, import types directly from `spaps-sdk`:
-
-```ts
-import { SPAPSClient, type User, type Session, type Role } from 'spaps-sdk';
-```
-
-For advanced or library use cases, you can also import canonical types from the standalone package:
-
-```ts
-import type {
-  User,
-  Session,
-  Role,
-  Permission,
-  TokenPayload,
-} from 'spaps-types';
-```
-
-Notes:
-- `spaps-sdk` re-exports commonly used types for convenience.
-- `spaps-types` is useful when building framework integrations, server middleware, or utilities that need to share types without depending on the SDK runtime.
-
-## Import Styles
-
-All these work:
-```javascript
-// ES6 Import
-import { SPAPSClient } from 'spaps-sdk';
-import SPAPSClient from 'spaps-sdk';
-
-// CommonJS
-const { SPAPSClient } = require('spaps-sdk');
-const SPAPSClient = require('spaps-sdk');
-
-// Alternative names
-import { SPAPS } from 'spaps-sdk';
-import { SweetPotatoSDK } from 'spaps-sdk';
 ```
 
 ## Admin API Methods
 
-The SDK includes comprehensive admin methods for Stripe product management:
-
-### Product Management
-
 ```typescript
-// Create product (Admin required)
-const product = await spaps.admin.createProduct({
+await spaps.admin.createProduct({
   name: 'Premium Plan',
   category: 'subscription',
-  description: 'Advanced features for power users',
-  images: ['https://example.com/product-image.jpg'],
-  metadata: { feature_set: 'premium' },
-  active: true
-});
-
-// Update product (Admin required)
-const updatedProduct = await spaps.admin.updateProduct('prod_123', {
-  name: 'Premium Plan Pro',
-  description: 'Updated features'
+  description: 'Advanced features',
 });
 
-// Archive product (Admin required)
-await spaps.admin.deleteProduct('prod_123');
-
-// Get products (includes admin metadata if user is admin)
-const { data } = await spaps.admin.getProducts();
-if (data.adminMetadata) {
-  console.log('Total revenue:', data.adminMetadata.total_revenue);
-}
-```
+await spaps.admin.updateProduct('prod_123', { name: 'Premium Plan Pro' });
 
-### Price Management
-
-```typescript
-// Create price (Admin required)
-const price = await spaps.admin.createPrice({
+await spaps.admin.createPrice({
   product_id: 'prod_123',
-  unit_amount: 2999, // $29.99
+  unit_amount: 2999,
   currency: 'usd',
   interval: 'month',
-  interval_count: 1,
-  nickname: 'Monthly Premium'
 });
 ```
 
-### Super Admin Operations
+## Helper Methods
 
 ```typescript
-// Sync all products from Stripe (Super Admin required)
-const syncResult = await spaps.admin.syncProducts();
-console.log(`Synced ${syncResult.data.synced_count} products`);
+spaps.isAuthenticated(); // boolean
+spaps.getAccessToken(); // string | undefined
+spaps.setAccessToken('token');
+spaps.isLocalMode(); // boolean
+await spaps.health();
 ```
 
-### Permission Checking
+## Troubleshooting
 
-```typescript
-// Check if current user can access admin features
-const user = await spaps.getCurrentUser();
-if (spaps.isAdmin(user)) {
-  // Show admin UI components
-  console.log('User has admin privileges');
-} else {
-  // Show regular user UI
-  console.log('Regular user');
-}
-```
+- `401 Unauthorized`: ensure valid access token and API key for non-local mode.
+- `403 Forbidden`: account lacks admin role for admin endpoints.
+- Local mode confusion: call `spaps.isLocalMode()` and verify `apiUrl`.
 
-## Error Handling
-
-```javascript
-try {
-  await spaps.admin.createProduct(productData);
-} catch (error) {
-  if (error.response?.status === 401) {
-    console.error('Authentication required');
-  } else if (error.response?.status === 403) {
-    console.error('Admin privileges required');
-  } else if (error.response?.status === 429) {
-    console.error('Rate limited');
-  } else {
-    console.error('Error:', error.message);
-  }
-}
+## Development
+
+From repository root:
+
+```bash
+cd packages/sdk
+npm ci
+npm run build
+npm run test
+npm run typecheck:readme
+npm run test:readme
 ```
 
+## Release
+
+- Main publish flow: `.github/workflows/publish.yml` (`publish-sdk` job).
+- Manual publish flow: `.github/workflows/npm-publish-manual.yml`.
+- npm credential source: repository secret `NPM_TOKEN`.
+
 ## License
 
 MIT

package/dist/index.js

@@ -648,28 +648,23 @@ var SPAPSClient = class {
     }
     if (!apiUrl || apiUrl.includes("localhost") || apiUrl.includes("127.0.0.1")) {
       this._isLocalMode = true;
-      this.client = import_axios.default.create({
-        baseURL: apiUrl || "http://localhost:3301",
-        timeout: config.timeout || 1e4,
-        headers: {
-          "Content-Type": "application/json"
-        }
-      });
-    } else {
-      if (!effectiveApiKey) {
-        console.warn("\u26A0\uFE0F SPAPS: No API key provided. Some features may not work.");
-      }
-      this.apiKey = effectiveApiKey;
-      this.client = import_axios.default.create({
-        baseURL: apiUrl,
-        timeout: config.timeout || 1e4,
-        headers: {
-          "Content-Type": "application/json",
-          ...this.apiKey && { "X-API-Key": this.apiKey }
-        }
-      });
     }
+    this.apiKey = effectiveApiKey;
+    if (!this.apiKey && !this._isLocalMode) {
+      console.warn("\u26A0\uFE0F SPAPS: No API key provided. Some features may not work.");
+    }
+    this.client = import_axios.default.create({
+      baseURL: apiUrl || "http://localhost:3301",
+      timeout: config.timeout || 1e4,
+      headers: {
+        "Content-Type": "application/json",
+        ...this.apiKey && { "X-API-Key": this.apiKey }
+      }
+    });
     this.client.interceptors.request.use((config2) => {
+      if (this.apiKey && !config2.headers["X-API-Key"]) {
+        config2.headers["X-API-Key"] = this.apiKey;
+      }
       if (this.accessToken && !config2.headers.Authorization) {
         config2.headers.Authorization = `Bearer ${this.accessToken}`;
       }

package/dist/index.mjs

@@ -618,28 +618,23 @@ var SPAPSClient = class {
     }
     if (!apiUrl || apiUrl.includes("localhost") || apiUrl.includes("127.0.0.1")) {
       this._isLocalMode = true;
-      this.client = axios.create({
-        baseURL: apiUrl || "http://localhost:3301",
-        timeout: config.timeout || 1e4,
-        headers: {
-          "Content-Type": "application/json"
-        }
-      });
-    } else {
-      if (!effectiveApiKey) {
-        console.warn("\u26A0\uFE0F SPAPS: No API key provided. Some features may not work.");
-      }
-      this.apiKey = effectiveApiKey;
-      this.client = axios.create({
-        baseURL: apiUrl,
-        timeout: config.timeout || 1e4,
-        headers: {
-          "Content-Type": "application/json",
-          ...this.apiKey && { "X-API-Key": this.apiKey }
-        }
-      });
     }
+    this.apiKey = effectiveApiKey;
+    if (!this.apiKey && !this._isLocalMode) {
+      console.warn("\u26A0\uFE0F SPAPS: No API key provided. Some features may not work.");
+    }
+    this.client = axios.create({
+      baseURL: apiUrl || "http://localhost:3301",
+      timeout: config.timeout || 1e4,
+      headers: {
+        "Content-Type": "application/json",
+        ...this.apiKey && { "X-API-Key": this.apiKey }
+      }
+    });
     this.client.interceptors.request.use((config2) => {
+      if (this.apiKey && !config2.headers["X-API-Key"]) {
+        config2.headers["X-API-Key"] = this.apiKey;
+      }
       if (this.accessToken && !config2.headers.Authorization) {
         config2.headers.Authorization = `Bearer ${this.accessToken}`;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps-sdk",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "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",
@@ -20,6 +20,8 @@
     "build": "tsup --tsconfig tsconfig.json src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup --tsconfig tsconfig.json src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
+    "test:readme": "vitest run test/readme-snippets.test.ts",
+    "typecheck:readme": "tsc -p tsconfig.readme.json --noEmit",
     "smoke-test": "npm run build && node smoke-test.js",
     "prepublishOnly": "npm run build && npm run smoke-test"
   },
@@ -36,10 +38,10 @@
     "scheduling"
   ],
   "author": "buildooor",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/build000r"
+    "url": "https://github.com/build000r/sweet-potato"
   },
   "homepage": "https://www.buildooor.com/services",
   "bugs": {
@@ -66,7 +68,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "PERMISSIONS.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -75,4 +79,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}