@seaverse/data-service-sdk 0.1.0 → 0.3.0

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 (7) hide show
  1. package/README.md +345 -114
  2. package/dist/index.cjs +140 -25
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.ts +255 -40
  5. package/dist/index.js +140 -25
  6. package/dist/index.js.map +1 -1
  7. package/package.json +10 -11
package/dist/index.js CHANGED
@@ -22,22 +22,72 @@ const ENDPOINTS = {
22
22
  /**
23
23
  * SeaVerse Data Service SDK Client
24
24
  *
25
- * Provides methods to manage Firestore tokens for authenticated users and guests.
25
+ * This client helps you get Firestore access tokens for your application.
26
+ * It supports both authenticated users and guest users.
27
+ *
28
+ * THREE-TIER PERMISSION MODEL:
29
+ * ---------------------------
30
+ * Your Firestore data is organized in three permission levels:
31
+ *
32
+ * 1. publicRead/ - System configs, announcements (Read: Everyone, Write: Admin only)
33
+ * 2. publicData/ - User posts, shared content (Read: Everyone, Write: Everyone)
34
+ * 3. userData/{userId}/ - Private user data (Read/Write: Owner only)
35
+ *
36
+ * QUICK START FOR LLM:
37
+ * -------------------
38
+ * Step 1: Get a Firestore token
39
+ * Step 2: Initialize Firebase with the token
40
+ * Step 3: Access Firestore using the correct data paths
26
41
  *
27
42
  * @example
28
43
  * ```typescript
29
- * // Create client instance
44
+ * // Step 1: Create client and get token
45
+ * import { DataServiceClient } from '@seaverse/data-service-sdk';
30
46
  * const client = new DataServiceClient();
31
47
  *
32
- * // Generate Firestore token for authenticated user
33
- * const token = await client.generateFirestoreToken({
34
- * token: 'user-jwt-token',
35
- * app_id: 'your-app-id',
48
+ * // For authenticated users:
49
+ * const tokenResponse = await client.generateFirestoreToken({
50
+ * token: 'user-jwt-token-from-auth-sdk',
51
+ * app_id: 'my-app-123',
52
+ * });
53
+ *
54
+ * // For guest users (no authentication required):
55
+ * const guestResponse = await client.generateGuestFirestoreToken({
56
+ * app_id: 'my-app-123',
57
+ * });
58
+ *
59
+ * // Step 2: Initialize Firebase
60
+ * import { initializeApp } from 'firebase/app';
61
+ * import { getAuth, signInWithCustomToken } from 'firebase/auth';
62
+ * import { getFirestore, collection, addDoc, getDocs, serverTimestamp } from 'firebase/firestore';
63
+ *
64
+ * const app = initializeApp({ projectId: tokenResponse.project_id });
65
+ * const auth = getAuth(app);
66
+ * await signInWithCustomToken(auth, tokenResponse.custom_token);
67
+ * const db = getFirestore(app);
68
+ *
69
+ * // Step 3: Access Firestore data with correct paths
70
+ * const appId = tokenResponse.app_id;
71
+ * const userId = tokenResponse.user_id;
72
+ *
73
+ * // Write to publicData (everyone can write)
74
+ * await addDoc(collection(db, `appData/${appId}/publicData/posts`), {
75
+ * _appId: appId, // REQUIRED: For data isolation
76
+ * _createdAt: serverTimestamp(), // REQUIRED: Server timestamp
77
+ * _createdBy: userId, // REQUIRED: Current user ID
78
+ * title: 'My Post', // Your custom fields
79
+ * content: 'Hello world'
36
80
  * });
37
81
  *
38
- * // Generate Firestore token for guest
39
- * const guestToken = await client.generateGuestFirestoreToken({
40
- * app_id: 'your-app-id',
82
+ * // Read from publicData (everyone can read)
83
+ * const snapshot = await getDocs(collection(db, `appData/${appId}/publicData/posts`));
84
+ *
85
+ * // Write to userData (only owner can write)
86
+ * await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
87
+ * _appId: appId, // REQUIRED
88
+ * _createdAt: serverTimestamp(), // REQUIRED
89
+ * _createdBy: userId, // REQUIRED
90
+ * note: 'Private note' // Your custom fields
41
91
  * });
42
92
  * ```
43
93
  */
@@ -86,8 +136,16 @@ class DataServiceClient {
86
136
  /**
87
137
  * Generate Firestore token for authenticated user
88
138
  *
89
- * This method generates a Firestore custom token for an authenticated user.
90
- * The user must provide a valid JWT token.
139
+ * Use this method when you have a logged-in user with a valid JWT token.
140
+ * The returned token allows access to:
141
+ * - publicRead data (read only)
142
+ * - publicData (read and write)
143
+ * - userData/{user_id} (read and write own data only)
144
+ *
145
+ * IMPORTANT FOR LLM: After getting the token, you MUST:
146
+ * 1. Initialize Firebase app with the project_id
147
+ * 2. Sign in with the custom_token using signInWithCustomToken()
148
+ * 3. Always include required fields in documents: _appId, _createdAt, _createdBy
91
149
  *
92
150
  * @param request - The request containing user token and app ID
93
151
  * @param options - Additional axios request configuration
@@ -95,14 +153,37 @@ class DataServiceClient {
95
153
  *
96
154
  * @example
97
155
  * ```typescript
98
- * const response = await client.generateFirestoreToken({
99
- * token: 'user-jwt-token',
100
- * app_id: 'my-app',
156
+ * // First, get user token from Auth SDK
157
+ * import { AuthClient } from '@seaverse/auth-sdk';
158
+ * const authClient = new AuthClient({ appId: 'my-app-123' });
159
+ * const loginResponse = await authClient.loginWithEmail({
160
+ * email: 'user@example.com',
161
+ * password: 'password123'
101
162
  * });
102
163
  *
103
- * console.log('Firestore ID Token:', response.id_token);
104
- * console.log('User ID:', response.user_id);
105
- * console.log('Expires in:', response.expires_in, 'seconds');
164
+ * // Then, get Firestore token
165
+ * import { DataServiceClient } from '@seaverse/data-service-sdk';
166
+ * const dataClient = new DataServiceClient();
167
+ * const firestoreToken = await dataClient.generateFirestoreToken({
168
+ * token: loginResponse.token, // JWT token from auth
169
+ * app_id: 'my-app-123'
170
+ * });
171
+ *
172
+ * console.log('Firestore Custom Token:', firestoreToken.custom_token);
173
+ * console.log('User ID:', firestoreToken.user_id);
174
+ * console.log('App ID:', firestoreToken.app_id);
175
+ * console.log('Token expires in:', firestoreToken.expires_in, 'seconds');
176
+ *
177
+ * // Now initialize Firebase and use Firestore
178
+ * import { initializeApp } from 'firebase/app';
179
+ * import { getAuth, signInWithCustomToken } from 'firebase/auth';
180
+ * import { getFirestore } from 'firebase/firestore';
181
+ *
182
+ * const app = initializeApp({ projectId: firestoreToken.project_id });
183
+ * const auth = getAuth(app);
184
+ * await signInWithCustomToken(auth, firestoreToken.custom_token);
185
+ * const db = getFirestore(app);
186
+ * // Ready to use Firestore!
106
187
  * ```
107
188
  */
108
189
  async generateFirestoreToken(request, options) {
@@ -116,10 +197,18 @@ class DataServiceClient {
116
197
  return response.data;
117
198
  }
118
199
  /**
119
- * Generate Firestore token for guest user
200
+ * Generate Firestore token for guest user (no authentication required)
201
+ *
202
+ * Use this method when you want to allow anonymous users to access your app.
203
+ * Guest users have limited permissions:
204
+ * - publicRead data (read only)
205
+ * - publicData (read and write, but cannot access other users' data)
206
+ * - CANNOT access userData (no private data access)
120
207
  *
121
- * This method generates a Firestore custom token for a guest (unauthenticated) user.
122
- * No user authentication token is required.
208
+ * IMPORTANT FOR LLM:
209
+ * - Guest users get a temporary user_id (e.g., 'guest-abc123')
210
+ * - Still need to include required fields: _appId, _createdAt, _createdBy
211
+ * - Great for public forums, comment sections, or demo apps
123
212
  *
124
213
  * @param request - The request containing app ID
125
214
  * @param options - Additional axios request configuration
@@ -127,13 +216,39 @@ class DataServiceClient {
127
216
  *
128
217
  * @example
129
218
  * ```typescript
130
- * const response = await client.generateGuestFirestoreToken({
131
- * app_id: 'my-app',
219
+ * // Get guest token (no user authentication needed!)
220
+ * import { DataServiceClient } from '@seaverse/data-service-sdk';
221
+ * const client = new DataServiceClient();
222
+ *
223
+ * const guestToken = await client.generateGuestFirestoreToken({
224
+ * app_id: 'my-app-123'
225
+ * });
226
+ *
227
+ * console.log('Guest Firestore Custom Token:', guestToken.custom_token);
228
+ * console.log('Guest User ID:', guestToken.user_id); // e.g., 'guest-abc123'
229
+ * console.log('Role:', guestToken.role); // 'guest'
230
+ *
231
+ * // Initialize Firebase with guest token
232
+ * import { initializeApp } from 'firebase/app';
233
+ * import { getAuth, signInWithCustomToken } from 'firebase/auth';
234
+ * import { getFirestore, collection, addDoc, serverTimestamp } from 'firebase/firestore';
235
+ *
236
+ * const app = initializeApp({ projectId: guestToken.project_id });
237
+ * const auth = getAuth(app);
238
+ * await signInWithCustomToken(auth, guestToken.custom_token);
239
+ * const db = getFirestore(app);
240
+ *
241
+ * // Guest can write to publicData
242
+ * await addDoc(collection(db, `appData/${guestToken.app_id}/publicData/comments`), {
243
+ * _appId: guestToken.app_id,
244
+ * _createdAt: serverTimestamp(),
245
+ * _createdBy: guestToken.user_id, // Guest user ID
246
+ * comment: 'Great app!',
247
+ * rating: 5
132
248
  * });
133
249
  *
134
- * console.log('Guest Firestore ID Token:', response.id_token);
135
- * console.log('Guest User ID:', response.user_id);
136
- * console.log('Role:', response.role); // 'guest'
250
+ * // Guest CANNOT write to userData (this will fail)
251
+ * // await addDoc(collection(db, `appData/${guestToken.app_id}/userData/${guestToken.user_id}/notes`), ...);
137
252
  * ```
138
253
  */
139
254
  async generateGuestFirestoreToken(request, options) {
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sources":["../src/config.ts","../src/client.ts"],"sourcesContent":[null,null],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.js","sources":["../src/config.ts","../src/client.ts"],"sourcesContent":[null,null],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@seaverse/data-service-sdk",
3
- "version": "0.1.0",
4
- "description": "SDK for SeaVerse Data Service - Firestore token management",
3
+ "version": "0.3.0",
4
+ "description": "SDK for SeaVerse Data Service - Firestore token management with three-tier permission model",
5
5
  "type": "module",
6
6
  "main": "dist/index.cjs",
7
7
  "module": "dist/index.js",
@@ -17,14 +17,6 @@
17
17
  "dist",
18
18
  "README.md"
19
19
  ],
20
- "scripts": {
21
- "build": "rollup -c",
22
- "build:tsc": "tsc",
23
- "dev": "ROLLUP_WATCH=true rollup -c -w",
24
- "clean": "rm -rf dist",
25
- "test": "vitest",
26
- "prepublishOnly": "npm run clean && npm run build"
27
- },
28
20
  "keywords": [
29
21
  "seaverse",
30
22
  "sdk",
@@ -55,5 +47,12 @@
55
47
  },
56
48
  "publishConfig": {
57
49
  "access": "public"
50
+ },
51
+ "scripts": {
52
+ "build": "rollup -c",
53
+ "build:tsc": "tsc",
54
+ "dev": "ROLLUP_WATCH=true rollup -c -w",
55
+ "clean": "rm -rf dist",
56
+ "test": "vitest"
58
57
  }
59
- }
58
+ }