@strands.gg/accui 1.0.2 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +138 -605
- package/dist/accui.css +0 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,673 +1,206 @@
|
|
|
1
1
|
# @strands.gg/accui
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
⚠️ **INTERNAL SYSTEM - NOT FOR PUBLIC USE** ⚠️
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
This is a proprietary authentication UI library specifically designed for the Strands Services ecosystem. It is tightly integrated with our internal authentication API and **will not easily function outside of our infrastructure**.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- **OAuth Providers** - Dynamic OAuth provider discovery from API
|
|
9
|
-
- **Vue 3 Composition API** - Built with modern Vue patterns
|
|
10
|
-
- **TypeScript Support** - Full type safety
|
|
11
|
-
- **Nuxt Module** - First-class Nuxt 3 & 4 support with auto-imports
|
|
12
|
-
- **Customizable UI** - Consistent design system with Tailwind CSS
|
|
13
|
-
- **Responsive Design** - Mobile-first approach
|
|
14
|
-
- **Route Protection** - Built-in middleware for authentication
|
|
7
|
+
## 🔒 System Requirements
|
|
15
8
|
|
|
16
|
-
|
|
9
|
+
This library requires:
|
|
10
|
+
- **Strands Accounts API** backend (proprietary)
|
|
11
|
+
- **Registered application** in our database
|
|
12
|
+
- **Valid domain** registered with Strands Services
|
|
13
|
+
- **Internal infrastructure** access
|
|
17
14
|
|
|
18
|
-
|
|
19
|
-
- ✅ **Proper Module Build** - Nuxt module now builds to both ES and CJS formats with runtime files
|
|
20
|
-
- ✅ **Auto-Import Styles** - Styles automatically imported with components (no manual CSS import needed)
|
|
21
|
-
- ✅ **Custom Styling Control** - `autoImportStyles: false` option for developers who want full styling control
|
|
22
|
-
- ✅ **Enhanced Nuxt Integration** - CSS automatically included in Nuxt builds
|
|
23
|
-
- ✅ **Simplified Setup** - Just install and use, styles are handled automatically
|
|
15
|
+
**This package is published for internal convenience only and cannot easily be used by external applications.**
|
|
24
16
|
|
|
25
|
-
##
|
|
17
|
+
## 🚀 Features (Internal Use Only)
|
|
26
18
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
**
|
|
34
|
-
|
|
35
|
-
- **Vue 3**: Styles load automatically when you import any component
|
|
36
|
-
- **Nuxt 3**: Styles are automatically included when you add the module
|
|
37
|
-
|
|
38
|
-
<details>
|
|
39
|
-
<summary>Manual CSS Import (if needed)</summary>
|
|
40
|
-
|
|
41
|
-
If you need to manually import styles for any reason:
|
|
42
|
-
|
|
43
|
-
```javascript
|
|
44
|
-
// Import the CSS in your main.js or app.vue
|
|
45
|
-
import '@strands.gg/accui/style.css'
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
</details>
|
|
49
|
-
|
|
50
|
-
## 🎯 Quick Start
|
|
51
|
-
|
|
52
|
-
### Basic Vue 3 Usage
|
|
53
|
-
|
|
54
|
-
```vue
|
|
55
|
-
<template>
|
|
56
|
-
<div>
|
|
57
|
-
<!-- Combined Auth Component with tabs -->
|
|
58
|
-
<StrandsAuth
|
|
59
|
-
@success="handleSuccess"
|
|
60
|
-
@error="handleError"
|
|
61
|
-
redirect-url="/dashboard"
|
|
62
|
-
/>
|
|
63
|
-
|
|
64
|
-
<!-- Or use individual components -->
|
|
65
|
-
<StrandsSignIn @success="handleSignInSuccess" />
|
|
66
|
-
<StrandsSignUp @success="handleSignUpSuccess" />
|
|
67
|
-
</div>
|
|
68
|
-
</template>
|
|
69
|
-
|
|
70
|
-
<script setup lang="ts">
|
|
71
|
-
import {
|
|
72
|
-
StrandsAuth,
|
|
73
|
-
StrandsSignIn,
|
|
74
|
-
StrandsSignUp,
|
|
75
|
-
useStrandsAuth
|
|
76
|
-
} from "@strands.gg/accui"
|
|
77
|
-
// Styles are automatically imported! ✨
|
|
78
|
-
|
|
79
|
-
// Access auth state globally
|
|
80
|
-
const { user, isAuthenticated, signOut } = useStrandsAuth()
|
|
81
|
-
|
|
82
|
-
const handleSuccess = (userData: any) => {
|
|
83
|
-
console.log("Authentication successful:", userData)
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
const handleError = (error: string) => {
|
|
87
|
-
console.error("Authentication error:", error)
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
const handleSignUpSuccess = (data: { email: string }) => {
|
|
91
|
-
console.log("Magic link sent to:", data.email)
|
|
92
|
-
}
|
|
93
|
-
</script>
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
### Nuxt 3 Module
|
|
97
|
-
|
|
98
|
-
Add the module to your `nuxt.config.ts`:
|
|
99
|
-
|
|
100
|
-
```typescript
|
|
101
|
-
export default defineNuxtConfig({
|
|
102
|
-
modules: ['@strands.gg/accui/nuxt'], // Styles auto-imported! ✨
|
|
103
|
-
|
|
104
|
-
// Public runtime configuration
|
|
105
|
-
runtimeConfig: {
|
|
106
|
-
public: {
|
|
107
|
-
strandsAuth: {
|
|
108
|
-
apiBaseUrl: 'https://accounts.mydomain.com',
|
|
109
|
-
clientId: 'your-client-id',
|
|
110
|
-
onSignInUrl: '/dashboard',
|
|
111
|
-
onSignOutUrl: '/',
|
|
112
|
-
accentColor: '#EA00A8'
|
|
113
|
-
}
|
|
114
|
-
}
|
|
115
|
-
}
|
|
116
|
-
})
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
**Available Configuration Options:**
|
|
120
|
-
|
|
121
|
-
```typescript
|
|
122
|
-
interface StrandsAuthConfig {
|
|
123
|
-
// Required
|
|
124
|
-
apiBaseUrl?: string // Default: 'https://your-api.example.com'
|
|
125
|
-
clientId?: string // Required for production
|
|
126
|
-
|
|
127
|
-
// Navigation
|
|
128
|
-
onSignInUrl?: string // Default: '/dashboard'
|
|
129
|
-
onSignOutUrl?: string // Default: '/'
|
|
130
|
-
redirectUrl?: string // OAuth callback URL
|
|
131
|
-
|
|
132
|
-
// Styling
|
|
133
|
-
accentColor?: string // Default: '#EA00A8'
|
|
134
|
-
autoImportStyles?: boolean // Default: true (disable for custom styling)
|
|
135
|
-
|
|
136
|
-
// Security & Performance
|
|
137
|
-
autoRefresh?: boolean // Default: true
|
|
138
|
-
refreshInterval?: number // Default: 4 (minutes)
|
|
139
|
-
|
|
140
|
-
// Route Protection
|
|
141
|
-
protectedRoutes?: string[] // Routes requiring authentication
|
|
142
|
-
guestOnlyRoutes?: string[] // Default: ['/auth', '/login', '/register']
|
|
143
|
-
|
|
144
|
-
// Development
|
|
145
|
-
devMode?: boolean // Default: false
|
|
146
|
-
}
|
|
147
|
-
```
|
|
19
|
+
- **Magic Link Authentication** - Passwordless signup flow via Strands email service
|
|
20
|
+
- **OAuth Providers** - Dynamic provider discovery from our API
|
|
21
|
+
- **Multi-Factor Authentication** - TOTP, email, and hardware key support
|
|
22
|
+
- **Dynamic CORS** - Automatic origin validation based on registered applications
|
|
23
|
+
- **Vue 3 & Nuxt Support** - Full framework integration
|
|
24
|
+
- **TypeScript** - Complete type safety
|
|
25
|
+
- **Session Management** - JWT token rotation with 5-minute expiry
|
|
148
26
|
|
|
149
|
-
|
|
27
|
+
## 🆕 Recent Updates
|
|
150
28
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
// API Configuration
|
|
159
|
-
apiBaseUrl: 'https://accounts.mydomain.com',
|
|
160
|
-
clientId: 'your-production-client-id',
|
|
161
|
-
|
|
162
|
-
// Navigation URLs
|
|
163
|
-
onSignInUrl: '/dashboard',
|
|
164
|
-
onSignOutUrl: '/welcome',
|
|
165
|
-
redirectUrl: '/auth/callback',
|
|
166
|
-
|
|
167
|
-
// Styling
|
|
168
|
-
accentColor: '#8b5cf6',
|
|
169
|
-
autoImportStyles: true, // Set to false for custom styling
|
|
170
|
-
|
|
171
|
-
// Route Protection
|
|
172
|
-
protectedRoutes: [
|
|
173
|
-
'/dashboard/*',
|
|
174
|
-
'/profile',
|
|
175
|
-
'/settings/*',
|
|
176
|
-
'/admin/*'
|
|
177
|
-
],
|
|
178
|
-
guestOnlyRoutes: [
|
|
179
|
-
'/auth',
|
|
180
|
-
'/login',
|
|
181
|
-
'/register',
|
|
182
|
-
'/welcome'
|
|
183
|
-
],
|
|
184
|
-
|
|
185
|
-
// Token Management
|
|
186
|
-
autoRefresh: true,
|
|
187
|
-
refreshInterval: 4, // minutes
|
|
188
|
-
|
|
189
|
-
// Development
|
|
190
|
-
devMode: process.env.NODE_ENV === 'development'
|
|
191
|
-
}
|
|
192
|
-
}
|
|
193
|
-
}
|
|
194
|
-
})
|
|
195
|
-
```
|
|
29
|
+
### v0.2.8+ (2025)
|
|
30
|
+
- ✅ **Dynamic Origin Support** - Removed hardcoded localhost references
|
|
31
|
+
- ✅ **OAuth2 Redirect URL** - Configurable OAuth callback URLs
|
|
32
|
+
- ✅ **Support Email Config** - Optional support contact display
|
|
33
|
+
- ✅ **CORS Improvements** - Fully dynamic based on registered applications
|
|
34
|
+
- ✅ **Neon Database Support** - Optimized connection pooling for serverless
|
|
35
|
+
- ✅ **Docker Optimizations** - Static binary builds with Alpine Linux
|
|
196
36
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
<StrandsAuth @success="handleAuth" />
|
|
203
|
-
<StrandsSignIn @success="handleSignIn" />
|
|
204
|
-
<StrandsSignUp @success="handleSignUp" />
|
|
205
|
-
<StrandsPasswordReset @success="handleReset" />
|
|
206
|
-
<StrandsUserProfile />
|
|
207
|
-
<StrandsMFASetup />
|
|
208
|
-
|
|
209
|
-
<!-- Utility Components (auto-imported) -->
|
|
210
|
-
<SignedIn>
|
|
211
|
-
<p>Welcome back, {{ user?.firstName }}!</p>
|
|
212
|
-
<StrandsUiButton @click="signOut">Sign Out</StrandsUiButton>
|
|
213
|
-
</SignedIn>
|
|
214
|
-
|
|
215
|
-
<SignedOut>
|
|
216
|
-
<p>Please sign in to continue</p>
|
|
217
|
-
<StrandsAuth />
|
|
218
|
-
</SignedOut>
|
|
219
|
-
|
|
220
|
-
<!-- Configuration & Branding -->
|
|
221
|
-
<StrandsConfigProvider :config="customConfig">
|
|
222
|
-
<!-- Scoped configuration -->
|
|
223
|
-
</StrandsConfigProvider>
|
|
224
|
-
|
|
225
|
-
<StrandsSecuredFooter />
|
|
226
|
-
</template>
|
|
227
|
-
|
|
228
|
-
<script setup lang="ts">
|
|
229
|
-
// Composables are auto-imported in Nuxt
|
|
230
|
-
const { user, isAuthenticated, signOut, signIn } = useStrandsAuth()
|
|
231
|
-
const authUser = useAuthUser() // Reactive user object
|
|
232
|
-
const { isAuthenticated: authState, isLoading } = useAuthState()
|
|
233
|
-
|
|
234
|
-
// Event handlers
|
|
235
|
-
const handleAuth = (userData: any) => {
|
|
236
|
-
console.log('Authentication successful:', userData)
|
|
237
|
-
// User is automatically redirected based on onSignInUrl
|
|
238
|
-
}
|
|
239
|
-
|
|
240
|
-
const handleSignUp = (data: { email: string }) => {
|
|
241
|
-
console.log('Magic link sent to:', data.email)
|
|
242
|
-
// Show success message to user
|
|
243
|
-
}
|
|
244
|
-
</script>
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
**Route Protection with Middleware:**
|
|
248
|
-
|
|
249
|
-
```vue
|
|
250
|
-
<!-- pages/dashboard/index.vue -->
|
|
251
|
-
<script setup lang="ts">
|
|
252
|
-
// Protect this route - redirects to auth if not signed in
|
|
253
|
-
definePageMeta({
|
|
254
|
-
middleware: 'auth'
|
|
255
|
-
})
|
|
256
|
-
</script>
|
|
257
|
-
|
|
258
|
-
<template>
|
|
259
|
-
<div>
|
|
260
|
-
<h1>Dashboard</h1>
|
|
261
|
-
<p>Protected content here</p>
|
|
262
|
-
</div>
|
|
263
|
-
</template>
|
|
264
|
-
```
|
|
37
|
+
### Previous Updates
|
|
38
|
+
- ✅ **MFA Support** - TOTP, email codes, hardware keys (WebAuthn)
|
|
39
|
+
- ✅ **Improved Error Handling** - Better user feedback
|
|
40
|
+
- ✅ **Auto-Import Styles** - Zero-config styling
|
|
41
|
+
- ✅ **Nuxt 4 Support** - Dedicated module for Nuxt v4
|
|
265
42
|
|
|
266
|
-
|
|
267
|
-
<!-- pages/auth.vue -->
|
|
268
|
-
<script setup lang="ts">
|
|
269
|
-
// Guest-only route - redirects away if already signed in
|
|
270
|
-
definePageMeta({
|
|
271
|
-
middleware: 'guest'
|
|
272
|
-
})
|
|
273
|
-
</script>
|
|
43
|
+
## 📦 Installation (Internal Projects Only)
|
|
274
44
|
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
<StrandsAuth />
|
|
278
|
-
</div>
|
|
279
|
-
</template>
|
|
45
|
+
```bash
|
|
46
|
+
npm install @strands.gg/accui
|
|
280
47
|
```
|
|
281
48
|
|
|
282
|
-
|
|
49
|
+
## 🎯 Configuration
|
|
283
50
|
|
|
284
|
-
|
|
51
|
+
### Nuxt 3/4 Configuration
|
|
285
52
|
|
|
286
53
|
```typescript
|
|
287
54
|
export default defineNuxtConfig({
|
|
288
|
-
modules: [
|
|
55
|
+
modules: [
|
|
56
|
+
'@strands.gg/accui/nuxt', // Nuxt 3
|
|
57
|
+
// OR
|
|
58
|
+
'@strands.gg/accui/nuxt-v4' // Nuxt 4
|
|
59
|
+
],
|
|
289
60
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
61
|
+
strandsAuth: {
|
|
62
|
+
// API endpoint (required)
|
|
63
|
+
baseUrl: process.env.NODE_ENV === 'development'
|
|
64
|
+
? 'http://localhost:8000'
|
|
65
|
+
: 'https://your-api.example.com',
|
|
66
|
+
|
|
67
|
+
// Navigation
|
|
68
|
+
onSignInUrl: '/dashboard',
|
|
69
|
+
onSignOutUrl: '/',
|
|
70
|
+
|
|
71
|
+
// OAuth2 configuration
|
|
72
|
+
oauth2RedirectUrl: 'https://your-app.example.com/oauth2/callback', // Optional
|
|
73
|
+
|
|
74
|
+
// Support
|
|
75
|
+
supportEmail: 'support@your-app.example.com', // Optional
|
|
76
|
+
|
|
77
|
+
// Development
|
|
78
|
+
devMode: process.env.NODE_ENV === 'development',
|
|
79
|
+
|
|
80
|
+
// Styling
|
|
81
|
+
accentColor: '#EA00A8',
|
|
82
|
+
styles: true, // Auto-import CSS
|
|
83
|
+
|
|
84
|
+
// Security
|
|
85
|
+
autoRefresh: true,
|
|
86
|
+
refreshInterval: 4, // minutes
|
|
87
|
+
|
|
88
|
+
// Route protection
|
|
89
|
+
protectedRoutes: ['/dashboard/*', '/admin/*'],
|
|
90
|
+
guestOnlyRoutes: ['/auth', '/login', '/register']
|
|
301
91
|
}
|
|
302
92
|
})
|
|
303
|
-
```
|
|
304
|
-
|
|
305
|
-
**Key Differences for Nuxt v4:**
|
|
306
|
-
|
|
307
|
-
- **Module Import**: Use `@strands.gg/accui/nuxt-v4` instead of `@strands.gg/accui/nuxt`
|
|
308
|
-
- **Compatibility**: Built specifically for Nuxt 4.0+ with updated APIs
|
|
309
|
-
- **Same API**: All configuration options and components remain identical
|
|
310
|
-
- **Future-Ready**: Optimized for Nuxt 4's performance improvements
|
|
311
|
-
|
|
312
|
-
**Migration from Nuxt 3 to Nuxt 4:**
|
|
313
|
-
|
|
314
|
-
```diff
|
|
315
|
-
export default defineNuxtConfig({
|
|
316
|
-
- modules: ['@strands.gg/accui/nuxt'],
|
|
317
|
-
+ modules: ['@strands.gg/accui/nuxt-v4'],
|
|
318
|
-
|
|
319
|
-
// Rest of config stays the same!
|
|
320
|
-
runtimeConfig: { /* ... */ }
|
|
321
|
-
})
|
|
322
|
-
```
|
|
323
93
|
|
|
324
94
|
## 🧩 Components
|
|
325
95
|
|
|
326
96
|
### Authentication Components
|
|
327
97
|
|
|
328
|
-
| Component | Description |
|
|
329
|
-
|
|
330
|
-
| `StrandsAuth` | Combined auth with tabs |
|
|
331
|
-
| `StrandsSignIn` | Email + password
|
|
332
|
-
| `StrandsSignUp` | Magic link signup |
|
|
333
|
-
| `
|
|
334
|
-
| `
|
|
335
|
-
| `StrandsUserProfile` | Profile management | User settings |
|
|
336
|
-
| `StrandsMFASetup` | Multi-factor auth setup | Security enhancement |
|
|
337
|
-
|
|
338
|
-
### Utility Components
|
|
339
|
-
|
|
340
|
-
| Component | Description |
|
|
341
|
-
|-----------|-------------|
|
|
342
|
-
| `SignedIn` | Conditional rendering for authenticated users |
|
|
343
|
-
| `SignedOut` | Conditional rendering for unauthenticated users |
|
|
344
|
-
| `StrandsConfigProvider` | Scoped configuration provider |
|
|
345
|
-
| `StrandsLogo` | Strands branding logo |
|
|
346
|
-
| `StrandsSecuredFooter` | "Secured by Strands" footer |
|
|
347
|
-
|
|
348
|
-
### UI Components
|
|
349
|
-
|
|
350
|
-
| Component | Description | Props |
|
|
351
|
-
|-----------|-------------|-------|
|
|
352
|
-
| `UiButton` | Styled button | `variant`, `size`, `loading`, `disabled` |
|
|
353
|
-
| `UiInput` | Form input field | `type`, `label`, `error`, `placeholder` |
|
|
354
|
-
| `UiCard` | Container card | `variant`, `shadow`, `padding` |
|
|
355
|
-
| `UiTabs` | Tab navigation | `tabs`, `modelValue` |
|
|
356
|
-
| `UiAlert` | Status messages | `variant`, `message` |
|
|
357
|
-
| `UiLink` | Styled link | `variant`, `size` |
|
|
358
|
-
|
|
359
|
-
## � Nuxt Module Features
|
|
360
|
-
|
|
361
|
-
The Nuxt module provides a complete authentication solution with:
|
|
362
|
-
|
|
363
|
-
### ✨ **Auto-Registration**
|
|
364
|
-
- **Components**: All authentication and UI components are automatically imported
|
|
365
|
-
- **Composables**: Authentication state management available globally
|
|
366
|
-
- **Middleware**: Route protection built-in (`auth`, `guest`, global middleware)
|
|
367
|
-
- **Types**: Full TypeScript support with auto-completion
|
|
368
|
-
- **Styles**: CSS automatically included in your Nuxt build
|
|
369
|
-
|
|
370
|
-
### 🎨 **Auto-Import Styles**
|
|
371
|
-
The Nuxt module automatically includes all necessary CSS:
|
|
372
|
-
```typescript
|
|
373
|
-
// Automatically added to your project:
|
|
374
|
-
// - Main component styles (@strands.gg/accui/style.css)
|
|
375
|
-
// - Custom accent color variables
|
|
376
|
-
// - Responsive design classes
|
|
377
|
-
// - Dark/light mode support
|
|
378
|
-
```
|
|
98
|
+
| Component | Description | Requirements |
|
|
99
|
+
|-----------|-------------|--------------|
|
|
100
|
+
| `StrandsAuth` | Combined auth with tabs | Valid application domain |
|
|
101
|
+
| `StrandsSignIn` | Email + password/MFA | Registered user account |
|
|
102
|
+
| `StrandsSignUp` | Magic link signup | SMTP configuration |
|
|
103
|
+
| `StrandsUserProfile` | Profile management | Active session |
|
|
104
|
+
| `StrandsMFASetup` | MFA configuration | User with verified email |
|
|
379
105
|
|
|
380
|
-
|
|
381
|
-
```typescript
|
|
382
|
-
export default defineNuxtConfig({
|
|
383
|
-
modules: ['@strands.gg/accui/nuxt'],
|
|
384
|
-
runtimeConfig: {
|
|
385
|
-
public: {
|
|
386
|
-
strandsAuth: {
|
|
387
|
-
apiBaseUrl: 'https://accounts.mydomain.com',
|
|
388
|
-
clientId: 'your-client-id',
|
|
389
|
-
autoImportStyles: false, // Disable auto-import
|
|
390
|
-
// ... other options
|
|
391
|
-
}
|
|
392
|
-
}
|
|
393
|
-
},
|
|
394
|
-
// Manually control CSS imports
|
|
395
|
-
css: [
|
|
396
|
-
// Import only base styles
|
|
397
|
-
'@strands.gg/accui/style.css',
|
|
398
|
-
// Or use your own custom styles
|
|
399
|
-
'~/assets/css/custom-auth.css'
|
|
400
|
-
]
|
|
401
|
-
})
|
|
402
|
-
```
|
|
106
|
+
### Composables
|
|
403
107
|
|
|
404
|
-
### 🔒 **Route Protection**
|
|
405
108
|
```typescript
|
|
406
|
-
//
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
- Custom CSS variables for theming
|
|
413
|
-
- Configurable accent colors
|
|
414
|
-
- TailwindCSS compatibility
|
|
415
|
-
- Dark/light mode support
|
|
416
|
-
|
|
417
|
-
### ⚡ **Performance Optimized**
|
|
418
|
-
- Client-side hydration with SSR support
|
|
419
|
-
- Automatic token refresh
|
|
420
|
-
- Minimal bundle size impact
|
|
421
|
-
- Tree-shaking optimized
|
|
422
|
-
|
|
423
|
-
### 🛠️ **Developer Experience**
|
|
424
|
-
- Hot reload support
|
|
425
|
-
- Development mode with debug logging
|
|
426
|
-
- TypeScript definitions included
|
|
427
|
-
- Comprehensive error handling
|
|
428
|
-
|
|
429
|
-
## �🔧 Composables
|
|
430
|
-
|
|
431
|
-
### `useStrandsAuth()`
|
|
432
|
-
|
|
433
|
-
Global authentication state management with clean integration points:
|
|
434
|
-
|
|
435
|
-
```typescript
|
|
436
|
-
const {
|
|
437
|
-
user, // Current user object
|
|
438
|
-
isAuthenticated, // Boolean auth status
|
|
439
|
-
isLoading, // Loading state
|
|
440
|
-
signOut, // Sign out function
|
|
441
|
-
refreshUser // Refresh user data
|
|
109
|
+
// Auto-imported in Nuxt
|
|
110
|
+
const {
|
|
111
|
+
user, // Current user from JWT
|
|
112
|
+
isAuthenticated, // Session validity
|
|
113
|
+
signOut, // Clear session
|
|
114
|
+
refreshToken // Rotate JWT token
|
|
442
115
|
} = useStrandsAuth()
|
|
443
116
|
|
|
444
|
-
//
|
|
445
|
-
// Replace placeholder implementations with actual auth service calls
|
|
446
|
-
```
|
|
447
|
-
|
|
448
|
-
### `useStrandsConfig()`
|
|
449
|
-
|
|
450
|
-
Configuration management:
|
|
451
|
-
|
|
452
|
-
```typescript
|
|
117
|
+
// OAuth providers from API
|
|
453
118
|
const {
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
```
|
|
458
|
-
|
|
459
|
-
### `useOAuthProviders()`
|
|
460
|
-
|
|
461
|
-
OAuth provider management:
|
|
462
|
-
|
|
463
|
-
```typescript
|
|
464
|
-
const {
|
|
465
|
-
enabledProviders, // Available OAuth providers
|
|
466
|
-
loading, // Loading state
|
|
467
|
-
error, // Error state
|
|
468
|
-
fetchProviders, // Fetch providers from API
|
|
469
|
-
redirectToProvider // Initiate OAuth flow
|
|
119
|
+
providers, // Available OAuth providers
|
|
120
|
+
fetchProviders, // Load from API
|
|
121
|
+
redirectToProvider // Initiate OAuth flow
|
|
470
122
|
} = useOAuthProviders()
|
|
471
123
|
```
|
|
472
124
|
|
|
473
|
-
##
|
|
474
|
-
|
|
475
|
-
The signup component uses a modern magic link approach:
|
|
476
|
-
|
|
477
|
-
```vue
|
|
478
|
-
<template>
|
|
479
|
-
<!-- User enters email only -->
|
|
480
|
-
<StrandsSignUp @success="handleMagicLinkSent" />
|
|
481
|
-
</template>
|
|
482
|
-
|
|
483
|
-
<script setup lang="ts">
|
|
484
|
-
// User receives magic link via email
|
|
485
|
-
// Clicking link completes registration
|
|
486
|
-
const handleMagicLinkSent = (data: { email: string }) => {
|
|
487
|
-
// Show success message
|
|
488
|
-
console.log(`Magic link sent to ${data.email}`)
|
|
489
|
-
}
|
|
490
|
-
</script>
|
|
491
|
-
```
|
|
492
|
-
|
|
493
|
-
## 🔐 Configuration
|
|
494
|
-
|
|
495
|
-
### Global Configuration
|
|
496
|
-
|
|
497
|
-
```typescript
|
|
498
|
-
import { setStrandsConfig } from '@strands.gg/accui'
|
|
499
|
-
|
|
500
|
-
setStrandsConfig({
|
|
501
|
-
apiBaseUrl: 'https://your-api.com',
|
|
502
|
-
clientId: 'your-client-id',
|
|
503
|
-
// Additional options
|
|
504
|
-
})
|
|
505
|
-
```
|
|
506
|
-
|
|
507
|
-
### Scoped Configuration
|
|
508
|
-
|
|
509
|
-
```vue
|
|
510
|
-
<template>
|
|
511
|
-
<StrandsConfigProvider :config="scopedConfig">
|
|
512
|
-
<StrandsAuth />
|
|
513
|
-
</StrandsConfigProvider>
|
|
514
|
-
</template>
|
|
515
|
-
|
|
516
|
-
<script setup lang="ts">
|
|
517
|
-
const scopedConfig = {
|
|
518
|
-
apiBaseUrl: 'https://different-api.com'
|
|
519
|
-
}
|
|
520
|
-
</script>
|
|
521
|
-
```
|
|
522
|
-
|
|
523
|
-
## 🎯 OAuth Integration
|
|
524
|
-
|
|
525
|
-
OAuth providers are dynamically loaded from your API endpoint:
|
|
526
|
-
|
|
527
|
-
```javascript
|
|
528
|
-
// GET /api/v1/oauth/providers
|
|
529
|
-
{
|
|
530
|
-
"providers": [
|
|
531
|
-
{
|
|
532
|
-
"id": "google",
|
|
533
|
-
"name": "Google",
|
|
534
|
-
"displayName": "Google",
|
|
535
|
-
"iconUrl": "https://example.com/google-icon.svg",
|
|
536
|
-
"enabled": true
|
|
537
|
-
}
|
|
538
|
-
]
|
|
539
|
-
}
|
|
540
|
-
```
|
|
541
|
-
|
|
542
|
-
## 📱 Responsive Design
|
|
125
|
+
## 🔐 Authentication Flow
|
|
543
126
|
|
|
544
|
-
|
|
127
|
+
1. **Sign Up**: Email → Magic Link → Complete Registration
|
|
128
|
+
2. **Sign In**: Email + Password → Optional MFA → JWT Token
|
|
129
|
+
3. **Token Rotation**: 5-minute access tokens, 30-day refresh tokens
|
|
130
|
+
4. **OAuth**: Dynamic provider discovery → Authorization → Callback
|
|
545
131
|
|
|
546
|
-
|
|
547
|
-
- **Tablet**: Adaptive spacing and sizing
|
|
548
|
-
- **Desktop**: Full-featured experience
|
|
132
|
+
## 🎨 Styling
|
|
549
133
|
|
|
550
|
-
|
|
134
|
+
Components use Tailwind CSS with custom properties:
|
|
551
135
|
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
# Ensure module is in nuxt.config.ts modules array
|
|
558
|
-
# Ensure you're using version 0.0.8+ which includes the fixed module build
|
|
559
|
-
```
|
|
560
|
-
|
|
561
|
-
**"Cannot find module './nuxt/module'" error:**
|
|
562
|
-
```bash
|
|
563
|
-
# This was fixed in v0.0.8 - update to the latest version:
|
|
564
|
-
npm update @strands.gg/accui
|
|
565
|
-
```
|
|
566
|
-
|
|
567
|
-
**TypeScript errors:**
|
|
568
|
-
```typescript
|
|
569
|
-
// Add type declaration in nuxt.config.ts
|
|
570
|
-
declare module '@nuxt/schema' {
|
|
571
|
-
interface RuntimeConfig {
|
|
572
|
-
public: {
|
|
573
|
-
strandsAuth: StrandsAuthConfig
|
|
574
|
-
}
|
|
575
|
-
}
|
|
136
|
+
```css
|
|
137
|
+
:root {
|
|
138
|
+
--strands-primary: #EA00A8; /* Strands brand color */
|
|
139
|
+
--strands-secondary: #B8006F;
|
|
140
|
+
/* Set via accentColor config */
|
|
576
141
|
}
|
|
577
142
|
```
|
|
578
143
|
|
|
579
|
-
|
|
580
|
-
```typescript
|
|
581
|
-
// Verify module configuration
|
|
582
|
-
modules: ['@strands.gg/accui/nuxt']
|
|
583
|
-
```
|
|
584
|
-
|
|
585
|
-
**Styles not loading:**
|
|
144
|
+
To use custom styles:
|
|
586
145
|
```typescript
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
strandsAuth: {
|
|
591
|
-
autoImportStyles: true // Enable auto-import
|
|
592
|
-
}
|
|
593
|
-
}
|
|
594
|
-
}
|
|
595
|
-
|
|
596
|
-
// Or manually import styles:
|
|
597
|
-
export default defineNuxtConfig({
|
|
598
|
-
css: ['@strands.gg/accui/style.css'] // Manual import
|
|
599
|
-
})
|
|
600
|
-
|
|
601
|
-
// For completely custom styling:
|
|
602
|
-
runtimeConfig: {
|
|
603
|
-
public: {
|
|
604
|
-
strandsAuth: {
|
|
605
|
-
autoImportStyles: false // Disable auto-import
|
|
606
|
-
}
|
|
607
|
-
}
|
|
146
|
+
strandsAuth: {
|
|
147
|
+
styles: false, // Disable auto-import
|
|
148
|
+
// ... other config
|
|
608
149
|
}
|
|
609
150
|
```
|
|
610
151
|
|
|
611
|
-
|
|
612
|
-
```vue
|
|
613
|
-
<!-- Ensure pages are in pages/ directory -->
|
|
614
|
-
<script setup lang="ts">
|
|
615
|
-
definePageMeta({
|
|
616
|
-
middleware: 'auth' // or 'guest'
|
|
617
|
-
})
|
|
618
|
-
</script>
|
|
619
|
-
```
|
|
152
|
+
## 🚨 Common Issues
|
|
620
153
|
|
|
621
|
-
###
|
|
154
|
+
### "Cannot connect to API"
|
|
155
|
+
- Verify your domain is registered with us
|
|
156
|
+
- Check CORS is enabled for your origin
|
|
157
|
+
- Ensure API is running (development: port 8000)
|
|
622
158
|
|
|
623
|
-
|
|
624
|
-
-
|
|
625
|
-
-
|
|
626
|
-
- Check for conflicting CSS frameworks
|
|
159
|
+
### "Invalid client configuration"
|
|
160
|
+
- Application domain must match request origin
|
|
161
|
+
- Cannot use from localhost without registration
|
|
627
162
|
|
|
628
|
-
|
|
629
|
-
-
|
|
630
|
-
-
|
|
631
|
-
-
|
|
163
|
+
### "MFA verification failed"
|
|
164
|
+
- TOTP codes expire after 30 seconds
|
|
165
|
+
- Email codes expire after 10 minutes
|
|
166
|
+
- Hardware keys require HTTPS origin
|
|
632
167
|
|
|
633
|
-
##
|
|
168
|
+
## 🔧 Development Setup
|
|
634
169
|
|
|
635
|
-
|
|
170
|
+
For local development of Strands applications, configure your Nuxt app to use the development API endpoint:
|
|
636
171
|
|
|
637
|
-
```
|
|
638
|
-
:
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
172
|
+
```typescript
|
|
173
|
+
strandsAuth: {
|
|
174
|
+
baseUrl: process.env.NODE_ENV === 'development'
|
|
175
|
+
? 'http://localhost:8000'
|
|
176
|
+
: 'https://your-api.example.com',
|
|
177
|
+
devMode: true
|
|
642
178
|
}
|
|
643
179
|
```
|
|
644
180
|
|
|
645
|
-
|
|
181
|
+
Contact the platform team to register your local development domain.
|
|
646
182
|
|
|
647
|
-
|
|
183
|
+
## 📋 TypeScript Types
|
|
648
184
|
|
|
649
185
|
```typescript
|
|
650
|
-
import type {
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
StrandsAuthConfig,
|
|
654
|
-
|
|
655
|
-
|
|
186
|
+
import type {
|
|
187
|
+
User, // User model from API
|
|
188
|
+
Session, // JWT session data
|
|
189
|
+
StrandsAuthConfig, // Module configuration
|
|
190
|
+
MfaDevice, // MFA device types
|
|
191
|
+
AuthResponse // API responses
|
|
656
192
|
} from '@strands.gg/accui'
|
|
657
193
|
```
|
|
658
194
|
|
|
659
|
-
##
|
|
195
|
+
## 🏗️ Requirements
|
|
660
196
|
|
|
661
|
-
- **
|
|
662
|
-
- **
|
|
663
|
-
- **TypeScript**: 5+ (optional but recommended)
|
|
664
|
-
- **Nuxt**: 3.0+ (for `/nuxt` module) or 4.0+ (for `/nuxt-v4` module)
|
|
197
|
+
- **Domain Registration**: Your application domain must be registered with Strands Services
|
|
198
|
+
- **HTTPS**: Required for production OAuth and hardware key authentication
|
|
665
199
|
|
|
666
200
|
## 📄 License
|
|
667
201
|
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
---
|
|
202
|
+
**PROPRIETARY - Strands Services Limited**
|
|
671
203
|
|
|
672
|
-
|
|
204
|
+
This software is the proprietary property of Strands Services Limited and may only be used in accordance with the terms of your agreement with Strands Services.
|
|
673
205
|
|
|
206
|
+
---
|
package/dist/accui.css
CHANGED