spaps-sdk 1.6.1 → 1.6.3

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# 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.2] - 2026-03-29
+
+### Added
+
+- Added canonical issue-reporting client methods for end-user create, list, detail, status, update, and reply flows.
+
+## [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