@sylphx/sdk 0.0.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.
Files changed (32) hide show
  1. package/README.md +432 -0
  2. package/dist/index.d.cts +13938 -0
  3. package/dist/index.d.ts +13938 -0
  4. package/dist/index.js +3291 -0
  5. package/dist/index.js.map +1 -0
  6. package/dist/index.mjs +3058 -0
  7. package/dist/index.mjs.map +1 -0
  8. package/dist/nextjs/index.d.cts +2089 -0
  9. package/dist/nextjs/index.d.ts +2089 -0
  10. package/dist/nextjs/index.js +1994 -0
  11. package/dist/nextjs/index.js.map +1 -0
  12. package/dist/nextjs/index.mjs +1941 -0
  13. package/dist/nextjs/index.mjs.map +1 -0
  14. package/dist/react/index.d.cts +14894 -0
  15. package/dist/react/index.d.ts +14894 -0
  16. package/dist/react/index.js +90818 -0
  17. package/dist/react/index.js.map +1 -0
  18. package/dist/react/index.mjs +90573 -0
  19. package/dist/react/index.mjs.map +1 -0
  20. package/dist/server/index.d.cts +9908 -0
  21. package/dist/server/index.d.ts +9908 -0
  22. package/dist/server/index.js +2733 -0
  23. package/dist/server/index.js.map +1 -0
  24. package/dist/server/index.mjs +2660 -0
  25. package/dist/server/index.mjs.map +1 -0
  26. package/dist/web-analytics.d.cts +90 -0
  27. package/dist/web-analytics.d.ts +90 -0
  28. package/dist/web-analytics.js +250 -0
  29. package/dist/web-analytics.js.map +1 -0
  30. package/dist/web-analytics.mjs +221 -0
  31. package/dist/web-analytics.mjs.map +1 -0
  32. package/package.json +98 -0
package/README.md ADDED
@@ -0,0 +1,432 @@
1
+ # @sylphx/sdk
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@sylphx/sdk.svg?style=flat)](https://www.npmjs.com/package/@sylphx/sdk)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
5
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?logo=typescript)](https://www.typescriptlang.org/)
6
+ [![docs](https://img.shields.io/badge/docs-sylphx.com%2Fdocs-green)](https://sylphx.com/docs)
7
+
8
+ Complete SDK for integrating apps with the Sylphx Platform. Get auth, billing, analytics, AI, storage, and more with minimal setup.
9
+
10
+ 📖 **Full documentation:** [sylphx.com/docs](https://sylphx.com/docs)
11
+
12
+ ## Installation
13
+
14
+ ```bash
15
+ npm install @sylphx/sdk
16
+ # or
17
+ pnpm add @sylphx/sdk
18
+ # or
19
+ bun add @sylphx/sdk
20
+ ```
21
+
22
+ ## Quick Start (Next.js)
23
+
24
+ ### 1. Environment Variables
25
+
26
+ ```bash
27
+ # .env.local
28
+ SYLPHX_APP_ID=your-app-slug
29
+ SYLPHX_APP_SECRET=sk_dev_xxxxxxxxxxxx
30
+ SYLPHX_PLATFORM_URL=https://sylphx.com
31
+ ```
32
+
33
+ ### 2. Add Provider to Layout
34
+
35
+ ```tsx
36
+ // app/layout.tsx
37
+ import { SylphxProvider } from '@sylphx/sdk/react'
38
+
39
+ export default function RootLayout({ children }) {
40
+ return (
41
+ <html>
42
+ <body>
43
+ <SylphxProvider appId={process.env.NEXT_PUBLIC_SYLPHX_APP_ID!}>
44
+ {children}
45
+ </SylphxProvider>
46
+ </body>
47
+ </html>
48
+ )
49
+ }
50
+ ```
51
+
52
+ ### 3. Add Middleware
53
+
54
+ ```ts
55
+ // middleware.ts
56
+ import { authMiddleware } from '@sylphx/sdk/nextjs'
57
+
58
+ export default authMiddleware({
59
+ appId: process.env.SYLPHX_APP_ID!,
60
+ publicRoutes: ['/', '/login', '/signup', '/api/auth/callback'],
61
+ })
62
+
63
+ export const config = {
64
+ matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
65
+ }
66
+ ```
67
+
68
+ ### 4. Create Callback Route
69
+
70
+ ```ts
71
+ // app/api/auth/callback/route.ts
72
+ import { handleCallback } from '@sylphx/sdk/nextjs'
73
+
74
+ export const GET = handleCallback()
75
+ ```
76
+
77
+ ### 5. Use the SDK
78
+
79
+ ```tsx
80
+ // app/page.tsx
81
+ 'use client'
82
+
83
+ import { useUser, SignedIn, SignedOut, SignIn, UserButton } from '@sylphx/sdk/react'
84
+
85
+ export default function Home() {
86
+ const { user } = useUser()
87
+
88
+ return (
89
+ <div>
90
+ <SignedOut>
91
+ <SignIn mode="embedded" afterSignInUrl="/dashboard" />
92
+ </SignedOut>
93
+
94
+ <SignedIn>
95
+ <h1>Hello, {user?.name}</h1>
96
+ <UserButton />
97
+ </SignedIn>
98
+ </div>
99
+ )
100
+ }
101
+ ```
102
+
103
+ ---
104
+
105
+ ## React Hooks
106
+
107
+ ### Authentication
108
+
109
+ ```tsx
110
+ import { useUser, useAuth, useSession } from '@sylphx/sdk/react'
111
+
112
+ // Get current user
113
+ const { user, isLoading, isSignedIn } = useUser()
114
+
115
+ // Auth actions
116
+ const { signIn, signUp, signOut, resetPassword } = useAuth()
117
+
118
+ // Session management
119
+ const { session, refresh } = useSession()
120
+ ```
121
+
122
+ ### Billing
123
+
124
+ ```tsx
125
+ import { useBilling } from '@sylphx/sdk/react'
126
+
127
+ const { subscription, isPremium, plans, createCheckout, openPortal } = useBilling()
128
+
129
+ // Check premium status
130
+ if (isPremium) {
131
+ // Show premium features
132
+ }
133
+
134
+ // Start checkout (returns URL to redirect to)
135
+ const checkoutUrl = await createCheckout('pro', 'monthly')
136
+ window.location.href = checkoutUrl
137
+
138
+ // Open billing portal to manage subscription
139
+ await openPortal()
140
+ ```
141
+
142
+ ### Analytics
143
+
144
+ ```tsx
145
+ import { useAnalytics } from '@sylphx/sdk/react'
146
+
147
+ const { track, identify, pageView } = useAnalytics()
148
+
149
+ // Track custom event
150
+ track('button_clicked', { buttonId: 'signup' })
151
+
152
+ // Identify user
153
+ identify({ name: 'John', email: 'john@example.com' })
154
+ ```
155
+
156
+ ### AI
157
+
158
+ ```tsx
159
+ import { useChat, useCompletion, useEmbedding } from '@sylphx/sdk/react'
160
+
161
+ // Chat completion
162
+ const { messages, send, isLoading } = useChat({
163
+ model: 'anthropic/claude-3.5-sonnet',
164
+ })
165
+
166
+ // Text completion
167
+ const { complete, completion, isLoading } = useCompletion()
168
+
169
+ // Embeddings
170
+ const { embed, embedding } = useEmbedding()
171
+ ```
172
+
173
+ ### Database
174
+
175
+ Server-side access to your Sylphx managed Postgres database with full type safety.
176
+
177
+ ```ts
178
+ import { createSylphx } from '@sylphx/sdk'
179
+
180
+ const sylphx = createSylphx({
181
+ appId: process.env.SYLPHX_APP_ID!,
182
+ appSecret: process.env.SYLPHX_APP_SECRET!,
183
+ })
184
+
185
+ // Execute raw SQL (returns typed rows)
186
+ const users = await sylphx.database.query<{ id: string; email: string }>(
187
+ 'SELECT id, email FROM users WHERE active = true LIMIT $1',
188
+ [100],
189
+ )
190
+
191
+ // Run migrations (idempotent)
192
+ await sylphx.database.migrate()
193
+
194
+ // Get connection string for ORMs (Prisma, Drizzle, etc.)
195
+ const connectionUrl = sylphx.database.connectionUrl()
196
+ ```
197
+
198
+ > **Tip:** Use the connection URL with your favourite ORM for full type-safety.
199
+ > The platform manages connection pooling automatically.
200
+
201
+ ### Storage
202
+
203
+ ```tsx
204
+ import { useStorage } from '@sylphx/sdk/react'
205
+
206
+ const { upload, uploadAvatar, deleteFile, getUrl, isUploading, progress } = useStorage()
207
+
208
+ // Upload avatar (special handling for profile images)
209
+ const avatarUrl = await uploadAvatar(file)
210
+
211
+ // Upload file with optional path
212
+ const fileUrl = await upload(file, { path: 'documents/' })
213
+
214
+ // Show progress while uploading
215
+ if (isUploading) {
216
+ console.log(`Upload progress: ${progress}%`)
217
+ }
218
+ ```
219
+
220
+ ### More Hooks
221
+
222
+ ```tsx
223
+ // Feature flags - check if features are enabled
224
+ import { useFeatureFlag, useFeatureFlags } from '@sylphx/sdk/react'
225
+ const { isEnabled, variant, isLoading } = useFeatureFlag('new-dashboard')
226
+ const flags = useFeatureFlags(['dark-mode', 'beta-features'])
227
+
228
+ // Error tracking - capture exceptions and breadcrumbs
229
+ import { useErrorTracking } from '@sylphx/sdk/react'
230
+ const { captureException, addBreadcrumb, setRoute } = useErrorTracking()
231
+
232
+ // Referrals - referral program management
233
+ import { useReferral } from '@sylphx/sdk/react'
234
+
235
+ // Privacy/consent - GDPR consent management
236
+ import { useConsent } from '@sylphx/sdk/react'
237
+
238
+ // Background jobs - async task management
239
+ import { useJobs } from '@sylphx/sdk/react'
240
+
241
+ // Organizations - multi-tenant support
242
+ import { useOrganization } from '@sylphx/sdk/react'
243
+
244
+ // Notifications - in-app notification center
245
+ import { useNotifications } from '@sylphx/sdk/react'
246
+ ```
247
+
248
+ ---
249
+
250
+ ## UI Components
251
+
252
+ ### Auth Components
253
+
254
+ ```tsx
255
+ import {
256
+ SignIn,
257
+ SignUp,
258
+ UserButton,
259
+ ForgotPassword,
260
+ ResetPassword,
261
+ VerifyEmail,
262
+ } from '@sylphx/sdk/react'
263
+
264
+ // Embedded sign-in form
265
+ <SignIn mode="embedded" afterSignInUrl="/dashboard" />
266
+
267
+ // Modal sign-in
268
+ <SignIn mode="modal" />
269
+
270
+ // User avatar with dropdown menu
271
+ <UserButton afterSignOutUrl="/" />
272
+ ```
273
+
274
+ ### Protected Routes
275
+
276
+ ```tsx
277
+ import { SignedIn, SignedOut, ProtectedRoute, Protect } from '@sylphx/sdk/react'
278
+
279
+ // Show only to signed-in users
280
+ <SignedIn>
281
+ <Dashboard />
282
+ </SignedIn>
283
+
284
+ // Show only to signed-out users
285
+ <SignedOut>
286
+ <SignIn mode="embedded" />
287
+ </SignedOut>
288
+
289
+ // Role-based access
290
+ <Protect role="admin">
291
+ <AdminPanel />
292
+ </Protect>
293
+ ```
294
+
295
+ ### Billing Components
296
+
297
+ ```tsx
298
+ import { PricingTable, BillingCard, CheckoutButton } from '@sylphx/sdk/react'
299
+
300
+ // Show pricing plans
301
+ <PricingTable plans={plans} />
302
+
303
+ // Current subscription card
304
+ <BillingCard />
305
+
306
+ // Checkout button
307
+ <CheckoutButton planSlug="pro" interval="monthly">
308
+ Upgrade to Pro
309
+ </CheckoutButton>
310
+ ```
311
+
312
+ ### Organization Components
313
+
314
+ ```tsx
315
+ import { OrganizationSwitcher, MembersList, InviteMember } from '@sylphx/sdk/react'
316
+
317
+ // Switch between orgs
318
+ <OrganizationSwitcher />
319
+
320
+ // Show org members
321
+ <MembersList />
322
+
323
+ // Invite form
324
+ <InviteMember onInvite={(email) => console.log(email)} />
325
+ ```
326
+
327
+ ---
328
+
329
+ ## Server-Side (Next.js)
330
+
331
+ ### Get Current User
332
+
333
+ ```tsx
334
+ // In Server Components
335
+ import { auth, currentUser } from '@sylphx/sdk/nextjs'
336
+
337
+ export default async function Page() {
338
+ const user = await currentUser()
339
+
340
+ if (!user) {
341
+ redirect('/login')
342
+ }
343
+
344
+ return <div>Hello, {user.name}</div>
345
+ }
346
+
347
+ // With full auth details
348
+ export default async function Page() {
349
+ const { userId, accessToken } = await auth()
350
+
351
+ // Use accessToken for API calls
352
+ }
353
+ ```
354
+
355
+ ### Server API Client
356
+
357
+ ```tsx
358
+ import { createSylphx } from '@sylphx/sdk'
359
+
360
+ const sylphx = createSylphx({
361
+ appId: process.env.SYLPHX_APP_ID!,
362
+ appSecret: process.env.SYLPHX_APP_SECRET!,
363
+ })
364
+
365
+ // Track events (tRPC-style with full type inference)
366
+ await sylphx.analytics.track.mutate({
367
+ event: 'purchase_completed',
368
+ userId: user.id,
369
+ properties: { amount: 99.99 },
370
+ })
371
+
372
+ // Get subscription
373
+ const subscription = await sylphx.billing.getSubscription.query()
374
+
375
+ // Check feature flag
376
+ const isEnabled = await sylphx.flags.check.query({ key: 'new-feature' })
377
+ ```
378
+
379
+ ---
380
+
381
+ ## API Reference
382
+
383
+ ### `createSylphx(config)`
384
+
385
+ Creates a server-side API client with full TypeScript inference.
386
+
387
+ ```ts
388
+ const sylphx = createSylphx({
389
+ appId: string, // Your app slug
390
+ appSecret: string, // sk_dev_*, sk_stg_*, or sk_prod_*
391
+ platformUrl?: string, // Default: https://sylphx.com
392
+ accessToken?: string, // User access token (optional)
393
+ })
394
+ ```
395
+
396
+ > **Note**: `createPlatformAPI` is deprecated. Use `createSylphx` instead.
397
+
398
+ **Available Namespaces:**
399
+
400
+ All methods use tRPC patterns: `.query()` for reads, `.mutate()` for writes.
401
+
402
+ | Namespace | Methods |
403
+ |-----------|---------|
404
+ | `auth` | `login`, `register`, `logout`, `verifyMfa`, `forgotPassword`, `resetPassword` |
405
+ | `user` | `getProfile`, `updateProfile`, `changePassword`, `getSecuritySettings`, `getLoginHistory`, `deleteAccount` |
406
+ | `billing` | `getPlans`, `getSubscription`, `createCheckout`, `createPortalSession`, `cancelSubscription` |
407
+ | `analytics` | `track`, `trackBatch`, `identify`, `pageView` |
408
+ | `notifications` | `list`, `markRead`, `getUnreadCount`, `getPreferences` |
409
+ | `referrals` | `getMyCode`, `redeem`, `getStats` |
410
+ | `flags` | `check`, `getAll`, `checkWithDetail`, `getAllWithDetail` |
411
+ | `storage` | `getUploadUrl`, `uploadAvatar` |
412
+ | `jobs` | `submit`, `getStatus`, `cancel`, `list` |
413
+
414
+ ---
415
+
416
+ ## Entry Points
417
+
418
+ | Import | Use For |
419
+ |--------|---------|
420
+ | `@sylphx/sdk` | Server-side API client |
421
+ | `@sylphx/sdk/react` | React hooks, components, provider |
422
+ | `@sylphx/sdk/nextjs` | Next.js middleware, auth helpers |
423
+
424
+ ---
425
+
426
+ ## TypeScript
427
+
428
+ Full type support included. No additional packages needed.
429
+
430
+ ```tsx
431
+ import type { User, Plan, Subscription } from '@sylphx/sdk'
432
+ ```