zopassport 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Zo World 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/README.md

@@ -0,0 +1,407 @@
+# 🌍 Zo Passport SDK
+
+> **One line reputation to rule the world**
+>
+> Phone OTP → Avatar → Passport → Wallet
+
+Complete authentication, onboarding, and passport experience for Zo World applications.
+
+---
+
+## 🚀 Quick Start - Get Running in 4 Commands
+
+```bash
+# 1. Create project and install
+mkdir my-zopassport && cd my-zopassport
+npm install zopassport
+
+# 2. Initialize the app
+npx create-zopassport
+
+# 3. Configure your client key
+cp .env.example .env
+# Edit .env: VITE_ZO_CLIENT_KEY=your-actual-key
+
+# 4. Run the app
+npm install && npm run dev
+```
+
+**That's it!** 🎉 Your full Zo Passport app is running at `http://localhost:5173`
+
+🔑 Get your client key at: **[https://zo.xyz/developers](https://zo.xyz/developers)**
+
+📖 [**Full Installation Guide →**](./INSTALL.md)
+
+---
+
+## 📦 What's Included
+
+After `npm install zopassport`, you get:
+
+✅ **Complete Demo App** - Full working phone → passport → wallet flow
+✅ **All Dependencies** - React, Vite, TypeScript pre-configured
+✅ **All Assets** - Images, videos, icons bundled
+✅ **Environment Template** - Just add your client key
+
+---
+
+## 🎯 For Developers - Use as SDK
+
+Want to integrate into your existing app? Use it as a library:
+
+### 1. Initialize the SDK
+
+```typescript
+import { ZoPassportSDK } from 'zopassport';
+
+const sdk = new ZoPassportSDK({
+  clientKey: 'your-client-key',
+  autoRefresh: true,
+});
+```
+
+### 2. React Integration
+
+```tsx
+import { ZoPassportProvider, useZoPassport, ZoLanding, ZoOnboarding, ZoPassportCard } from 'zopassport/react';
+
+function App() {
+  return (
+    <ZoPassportProvider clientKey="your-client-key">
+      <YourApp />
+    </ZoPassportProvider>
+  );
+}
+
+function YourApp() {
+  const { isAuthenticated, user, sendOTP, verifyOTP } = useZoPassport();
+
+  if (!isAuthenticated) {
+    return (
+      <ZoLanding
+        onAuthSuccess={(userId, user) => console.log('Logged in!', user)}
+        sendOTP={sendOTP}
+        verifyOTP={verifyOTP}
+      />
+    );
+  }
+
+  return (
+    <div>
+      <ZoPassportCard
+        profile={{
+          avatar: user.avatar?.image,
+          name: user.first_name,
+          isFounder: user.membership === 'founder',
+        }}
+        completion={{ done: 8, total: 10 }}
+      />
+    </div>
+  );
+}
+```
+
+## Features
+
+### ✅ Authentication
+- Phone number + OTP authentication
+- Automatic token refresh
+- Session persistence
+
+### ✅ Avatar Generation
+- Choose body type (Bro/Bae)
+- AI-powered avatar generation
+- Polling status updates
+
+### ✅ Passport Card
+- Leather texture design
+- Founder/Citizen variants
+- Progress ring indicator
+
+### ✅ Onboarding Flow
+- Nickname input
+- Location detection
+- Avatar preview
+
+## Components
+
+### `<ZoLanding />`
+Full-screen landing page with video background and auth modal.
+
+```tsx
+<ZoLanding
+  onAuthSuccess={(userId, user) => {}}
+  sendOTP={async (code, phone) => sdk.auth.sendOTP(code, phone)}
+  verifyOTP={async (code, phone, otp) => sdk.auth.verifyOTP(code, phone, otp)}
+  videoUrl="/videos/background.mp4"
+  logoUrl="/zo-logo.png"
+  title="ZOHMMM!"
+/>
+```
+
+### `<ZoOnboarding />`
+Complete onboarding flow component.
+
+```tsx
+<ZoOnboarding
+  onComplete={(data) => console.log(data)}
+  updateProfile={(updates) => sdk.updateProfile(updates)}
+  getProfile={() => sdk.getProfile()}
+/>
+```
+
+### `<ZoPassportCard />`
+Passport card display component.
+
+```tsx
+<ZoPassportCard
+  profile={{
+    avatar: 'https://...',
+    name: 'Samurai',
+    isFounder: true,
+  }}
+  completion={{ done: 8, total: 10 }}
+/>
+```
+
+### `<ZoAuth />`
+Standalone phone OTP authentication component.
+
+```tsx
+<ZoAuth
+  onSuccess={(userId, user) => {}}
+  onClose={() => {}}
+  sendOTP={sendOTP}
+  verifyOTP={verifyOTP}
+/>
+```
+
+### `<PhoneInput />` & `<OTPInput />`
+Low-level input components for custom auth flows.
+
+## Hooks
+
+### `useZoPassport()`
+Main hook for authentication state and operations.
+
+```tsx
+const {
+  sdk,
+  user,
+  isAuthenticated,
+  isLoading,
+  sendOTP,
+  verifyOTP,
+  logout,
+  refreshProfile,
+} = useZoPassport();
+```
+
+### `useProfile()`
+Profile operations and completion tracking.
+
+```tsx
+const {
+  user,
+  completion,
+  isFounder,
+  updateProfile,
+  reload,
+} = useProfile();
+```
+
+### `useAvatar()`
+Avatar generation operations.
+
+```tsx
+const {
+  avatarUrl,
+  isGenerating,
+  generateAvatar,
+} = useAvatar();
+```
+
+## Assets Required
+
+Include these assets in your `public/` folder:
+
+```
+public/
+├── figma-assets/
+│   └── landing-zo-logo.png          # Zo logo
+├── videos/
+│   └── loading-screen-background.mp4 # Background video
+├── bro.png                          # Bro avatar preview
+├── bae.png                          # Bae avatar preview
+├── Cultural Stickers/               # Culture icons
+│   ├── Travel&Adventure.png
+│   ├── Design.png
+│   ├── Science&Technology.png
+│   ├── Food.png
+│   ├── Music&Entertainment.png
+│   ├── Photography.png
+│   ├── Health&Fitness.png
+│   ├── Sport.png
+│   ├── Literature&Stories.png
+│   ├── Television&Cinema.png
+│   ├── Spiritual.png
+│   ├── Nature&Wildlife.png
+│   ├── Business.png
+│   ├── Law.png
+│   ├── Home&Lifestyle.png
+│   ├── Game.png
+│   └── Stories&Journal.png
+└── images/
+    └── rank1.jpeg                   # Fallback avatar
+```
+
+## CDN Assets
+
+The SDK uses these CDN URLs for passport backgrounds:
+
+- **Founder Background**: `https://proxy.cdn.zo.xyz/gallery/media/images/a1659b07-94f0-4490-9b3c-3366715d9717_20250515053726.png`
+- **Citizen Background**: `https://proxy.cdn.zo.xyz/gallery/media/images/bda9da5a-eefe-411d-8d90-667c80024463_20250515053805.png`
+
+You can override these via props.
+
+## Storage Adapters
+
+### Web (Default)
+Uses `localStorage` automatically.
+
+### React Native
+```tsx
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { ZoPassportSDK, AsyncStorageAdapter } from 'zopassport';
+
+const sdk = new ZoPassportSDK({
+  clientKey: 'your-key',
+  storageAdapter: new AsyncStorageAdapter(AsyncStorage),
+});
+```
+
+### Server-Side / Testing
+```tsx
+import { ZoPassportSDK, MemoryStorageAdapter } from 'zopassport';
+
+const sdk = new ZoPassportSDK({
+  clientKey: 'your-key',
+  storageAdapter: new MemoryStorageAdapter(),
+});
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  ZoUser,
+  ZoAuthResponse,
+  ZoProfileUpdatePayload,
+  ZoPassportConfig,
+} from 'zopassport';
+```
+
+## License
+
+MIT © Zo World Team
+
+## Wallet Integration
+
+The SDK includes a built-in wallet system for managing Zo World assets.
+
+### Framework-Agnostic Usage
+
+```typescript
+// Get wallet balance
+const balance = await sdk.wallet.getBalance();
+console.log('Balance:', balance.total_amount);
+
+// Get transaction history
+const transactions = await sdk.wallet.getTransactions();
+console.log('Transactions:', transactions);
+```
+
+### React Components
+
+The SDK provides ready-to-use wallet components:
+
+```tsx
+import { WalletScreen, WalletCard } from 'zopassport/react';
+
+// Full wallet screen
+<WalletScreen onBack={() => console.log('Back')} />
+
+// Wallet card widget
+<WalletCard 
+  balance={100} 
+  user={user} 
+  isOpen={isOpen} 
+  onToggle={() => setIsOpen(!isOpen)} 
+/>
+```
+
+### React Hooks
+
+```tsx
+import { useWalletBalance, useTransactions } from 'zopassport/react';
+
+const MyWallet = () => {
+  const { balance, isLoading } = useWalletBalance(sdk.client);
+  const { transactions } = useTransactions(sdk.client);
+
+  return <div>Balance: {balance}</div>;
+};
+```
+
+## Universal UI Support (Web + Mobile)
+
+The SDK's UI components are built with React Native but can run on the web using `react-native-web`.
+
+### Vite Configuration
+
+To use the UI components in a Vite app, configure your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      'react-native': 'react-native-web',
+      // Mock reanimated if not using web-compatible version
+      'react-native-reanimated': path.resolve(__dirname, './reanimated-mock.js'),
+    },
+    extensions: ['.web.js', '.web.ts', '.web.tsx', '.js', '.ts', '.tsx'],
+  },
+  define: {
+    global: 'window',
+  },
+});
+```
+
+### Next.js Configuration
+
+For Next.js, use `next-transpile-modules`:
+
+```javascript
+const withTM = require('next-transpile-modules')([
+  'zopassport',
+  'react-native-web',
+]);
+
+module.exports = withTM({
+  webpack: (config) => {
+    config.resolve.alias = {
+      ...(config.resolve.alias || {}),
+      'react-native$': 'react-native-web',
+    };
+    return config;
+  },
+});
+```
+

package/app/.env.example

@@ -0,0 +1,15 @@
+# ============================================
+# ZO PASSPORT CONFIGURATION  
+# ============================================
+# Get your client key from: https://zo.xyz/developers
+# 
+# Copy this file to .env and add your client key:
+#   cp .env.example .env
+#
+# Then edit .env with your actual key
+# ============================================
+
+VITE_ZO_CLIENT_KEY=your-client-key-here
+
+# Optional: Override the API base URL (default: https://api.io.zo.xyz)
+# VITE_ZO_API_URL=https://api.io.zo.xyz

package/app/README.md

@@ -0,0 +1,28 @@
+# Development Playground
+
+This directory is a **local development environment** for testing Zo Passport SDK components.
+
+## Purpose
+
+- Test React Native components in a web environment using mocks
+- Preview UI components during development
+- **NOT published to npm** (excluded from `files` in package.json)
+
+## Setup
+
+```bash
+cd app
+npm install
+npm run dev
+```
+
+## Mocks
+
+- `reanimated-mock.js` - Mocks `react-native-reanimated` for web
+- `svg-mock.js` - Mocks `react-native-svg` for web
+
+## Note
+
+The components here may be **out of sync** with the main `src/` directory.
+Always develop in `src/` and use this playground for quick visual testing.
+

package/app/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "zo-passport-demo",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "zopassport": "file:.."
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0"
+  }
+}
+

package/app/reanimated-mock.js

@@ -0,0 +1,102 @@
+// Mock for react-native-reanimated on web
+// Provides basic functionality that works in browser
+
+import { View, Text, Image, ScrollView, TouchableOpacity } from 'react-native-web';
+
+// Create animated versions of components
+const createAnimatedComponent = (Component) => {
+  const AnimatedComponent = ({ style, ...props }) => {
+    return <Component style={style} {...props} />;
+  };
+  AnimatedComponent.displayName = `Animated(${Component.displayName || Component.name || 'Component'})`;
+  return AnimatedComponent;
+};
+
+const Animated = {
+  View: createAnimatedComponent(View),
+  Text: createAnimatedComponent(Text),
+  Image: createAnimatedComponent(Image),
+  ScrollView: createAnimatedComponent(ScrollView),
+  createAnimatedComponent,
+};
+
+// Hooks
+export function useSharedValue(initialValue) {
+  return { value: initialValue };
+}
+
+export function useAnimatedStyle(worklet) {
+  return worklet();
+}
+
+export function useDerivedValue(worklet) {
+  return { value: worklet() };
+}
+
+export function useAnimatedScrollHandler() {
+  return {};
+}
+
+// Animation functions
+export function withTiming(toValue, config, callback) {
+  return toValue;
+}
+
+export function withSpring(toValue, config, callback) {
+  return toValue;
+}
+
+export function withDelay(delay, animation) {
+  return animation;
+}
+
+export function withRepeat(animation, numberOfReps, reverse, callback) {
+  return animation;
+}
+
+export function withSequence(...animations) {
+  return animations[animations.length - 1];
+}
+
+export function interpolate(value, inputRange, outputRange) {
+  return outputRange[0];
+}
+
+export const Easing = {
+  linear: (t) => t,
+  ease: (t) => t,
+  quad: (t) => t,
+  cubic: (t) => t,
+  bezier: () => (t) => t,
+  in: (fn) => fn,
+  out: (fn) => fn,
+  inOut: (fn) => fn,
+};
+
+// Layout animations
+export const FadeIn = { duration: () => FadeIn };
+export const FadeOut = { duration: () => FadeOut };
+export const FadeInUp = { duration: () => FadeInUp };
+export const FadeOutUp = { duration: () => FadeOutUp };
+export const FadeInDown = { duration: () => FadeInDown };
+export const SlideInRight = { duration: () => SlideInRight };
+export const SlideOutLeft = { duration: () => SlideOutLeft };
+
+// Functions
+export function runOnJS(fn) {
+  return fn;
+}
+
+export function runOnUI(fn) {
+  return fn;
+}
+
+export function cancelAnimation() {}
+
+export default Animated;
+
+
+
+
+
+

package/app/reanimated-mock.jsx

@@ -0,0 +1,97 @@
+// Mock for react-native-reanimated on web
+// Provides basic functionality that works in browser
+
+import { View, Text, Image, ScrollView, TouchableOpacity } from 'react-native-web';
+
+// Create animated versions of components
+const createAnimatedComponent = (Component) => {
+  const AnimatedComponent = ({ style, ...props }) => {
+    return <Component style={style} {...props} />;
+  };
+  AnimatedComponent.displayName = `Animated(${Component.displayName || Component.name || 'Component'})`;
+  return AnimatedComponent;
+};
+
+const Animated = {
+  View: createAnimatedComponent(View),
+  Text: createAnimatedComponent(Text),
+  Image: createAnimatedComponent(Image),
+  ScrollView: createAnimatedComponent(ScrollView),
+  createAnimatedComponent,
+};
+
+// Hooks
+export function useSharedValue(initialValue) {
+  return { value: initialValue };
+}
+
+export function useAnimatedStyle(worklet) {
+  return worklet();
+}
+
+export function useDerivedValue(worklet) {
+  return { value: worklet() };
+}
+
+export function useAnimatedScrollHandler() {
+  return {};
+}
+
+// Animation functions
+export function withTiming(toValue, config, callback) {
+  return toValue;
+}
+
+export function withSpring(toValue, config, callback) {
+  return toValue;
+}
+
+export function withDelay(delay, animation) {
+  return animation;
+}
+
+export function withRepeat(animation, numberOfReps, reverse, callback) {
+  return animation;
+}
+
+export function withSequence(...animations) {
+  return animations[animations.length - 1];
+}
+
+export function interpolate(value, inputRange, outputRange) {
+  return outputRange[0];
+}
+
+export const Easing = {
+  linear: (t) => t,
+  ease: (t) => t,
+  quad: (t) => t,
+  cubic: (t) => t,
+  bezier: () => (t) => t,
+  in: (fn) => fn,
+  out: (fn) => fn,
+  inOut: (fn) => fn,
+};
+
+// Layout animations
+export const FadeIn = { duration: () => FadeIn };
+export const FadeOut = { duration: () => FadeOut };
+export const FadeInUp = { duration: () => FadeInUp };
+export const FadeOutUp = { duration: () => FadeOutUp };
+export const FadeInDown = { duration: () => FadeInDown };
+export const SlideInRight = { duration: () => SlideInRight };
+export const SlideOutLeft = { duration: () => SlideOutLeft };
+
+// Functions
+export function runOnJS(fn) {
+  return fn;
+}
+
+export function runOnUI(fn) {
+  return fn;
+}
+
+export function cancelAnimation() {}
+
+export default Animated;
+