@seaverse/data-service-sdk 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -24,22 +24,72 @@ const ENDPOINTS = {
 /**
  * SeaVerse Data Service SDK Client
  *
- * Provides methods to manage Firestore tokens for authenticated users and guests.
+ * This client helps you get Firestore access tokens for your application.
+ * It supports both authenticated users and guest users.
+ *
+ * THREE-TIER PERMISSION MODEL:
+ * ---------------------------
+ * Your Firestore data is organized in three permission levels:
+ *
+ * 1. publicRead/   - System configs, announcements (Read: Everyone, Write: Admin only)
+ * 2. publicData/   - User posts, shared content (Read: Everyone, Write: Everyone)
+ * 3. userData/{userId}/ - Private user data (Read/Write: Owner only)
+ *
+ * QUICK START FOR LLM:
+ * -------------------
+ * Step 1: Get a Firestore token
+ * Step 2: Initialize Firebase with the token
+ * Step 3: Access Firestore using the correct data paths
  *
  * @example
  * ```typescript
- * // Create client instance
+ * // Step 1: Create client and get token
+ * import { DataServiceClient } from '@seaverse/data-service-sdk';
  * const client = new DataServiceClient();
  *
- * // Generate Firestore token for authenticated user
- * const token = await client.generateFirestoreToken({
- *   token: 'user-jwt-token',
- *   app_id: 'your-app-id',
+ * // For authenticated users:
+ * const tokenResponse = await client.generateFirestoreToken({
+ *   token: 'user-jwt-token-from-auth-sdk',
+ *   app_id: 'my-app-123',
+ * });
+ *
+ * // For guest users (no authentication required):
+ * const guestResponse = await client.generateGuestFirestoreToken({
+ *   app_id: 'my-app-123',
+ * });
+ *
+ * // Step 2: Initialize Firebase
+ * import { initializeApp } from 'firebase/app';
+ * import { getAuth, signInWithCustomToken } from 'firebase/auth';
+ * import { getFirestore, collection, addDoc, getDocs, serverTimestamp } from 'firebase/firestore';
+ *
+ * const app = initializeApp({ projectId: tokenResponse.project_id });
+ * const auth = getAuth(app);
+ * await signInWithCustomToken(auth, tokenResponse.custom_token);
+ * const db = getFirestore(app);
+ *
+ * // Step 3: Access Firestore data with correct paths
+ * const appId = tokenResponse.app_id;
+ * const userId = tokenResponse.user_id;
+ *
+ * // Write to publicData (everyone can write)
+ * await addDoc(collection(db, `appData/${appId}/publicData/posts`), {
+ *   _appId: appId,              // REQUIRED: For data isolation
+ *   _createdAt: serverTimestamp(), // REQUIRED: Server timestamp
+ *   _createdBy: userId,         // REQUIRED: Current user ID
+ *   title: 'My Post',           // Your custom fields
+ *   content: 'Hello world'
  * });
  *
- * // Generate Firestore token for guest
- * const guestToken = await client.generateGuestFirestoreToken({
- *   app_id: 'your-app-id',
+ * // Read from publicData (everyone can read)
+ * const snapshot = await getDocs(collection(db, `appData/${appId}/publicData/posts`));
+ *
+ * // Write to userData (only owner can write)
+ * await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
+ *   _appId: appId,              // REQUIRED
+ *   _createdAt: serverTimestamp(), // REQUIRED
+ *   _createdBy: userId,         // REQUIRED
+ *   note: 'Private note'        // Your custom fields
  * });
  * ```
  */
@@ -88,8 +138,16 @@ class DataServiceClient {
     /**
      * Generate Firestore token for authenticated user
      *
-     * This method generates a Firestore custom token for an authenticated user.
-     * The user must provide a valid JWT token.
+     * Use this method when you have a logged-in user with a valid JWT token.
+     * The returned token allows access to:
+     * - publicRead data (read only)
+     * - publicData (read and write)
+     * - userData/{user_id} (read and write own data only)
+     *
+     * IMPORTANT FOR LLM: After getting the token, you MUST:
+     * 1. Initialize Firebase app with the project_id
+     * 2. Sign in with the custom_token using signInWithCustomToken()
+     * 3. Always include required fields in documents: _appId, _createdAt, _createdBy
      *
      * @param request - The request containing user token and app ID
      * @param options - Additional axios request configuration
@@ -97,14 +155,37 @@ class DataServiceClient {
      *
      * @example
      * ```typescript
-     * const response = await client.generateFirestoreToken({
-     *   token: 'user-jwt-token',
-     *   app_id: 'my-app',
+     * // First, get user token from Auth SDK
+     * import { AuthClient } from '@seaverse/auth-sdk';
+     * const authClient = new AuthClient({ appId: 'my-app-123' });
+     * const loginResponse = await authClient.loginWithEmail({
+     *   email: 'user@example.com',
+     *   password: 'password123'
      * });
      *
-     * console.log('Firestore ID Token:', response.id_token);
-     * console.log('User ID:', response.user_id);
-     * console.log('Expires in:', response.expires_in, 'seconds');
+     * // Then, get Firestore token
+     * import { DataServiceClient } from '@seaverse/data-service-sdk';
+     * const dataClient = new DataServiceClient();
+     * const firestoreToken = await dataClient.generateFirestoreToken({
+     *   token: loginResponse.token,  // JWT token from auth
+     *   app_id: 'my-app-123'
+     * });
+     *
+     * console.log('Firestore Custom Token:', firestoreToken.custom_token);
+     * console.log('User ID:', firestoreToken.user_id);
+     * console.log('App ID:', firestoreToken.app_id);
+     * console.log('Token expires in:', firestoreToken.expires_in, 'seconds');
+     *
+     * // Now initialize Firebase and use Firestore
+     * import { initializeApp } from 'firebase/app';
+     * import { getAuth, signInWithCustomToken } from 'firebase/auth';
+     * import { getFirestore } from 'firebase/firestore';
+     *
+     * const app = initializeApp({ projectId: firestoreToken.project_id });
+     * const auth = getAuth(app);
+     * await signInWithCustomToken(auth, firestoreToken.custom_token);
+     * const db = getFirestore(app);
+     * // Ready to use Firestore!
      * ```
      */
     async generateFirestoreToken(request, options) {
@@ -118,10 +199,18 @@ class DataServiceClient {
         return response.data;
     }
     /**
-     * Generate Firestore token for guest user
+     * Generate Firestore token for guest user (no authentication required)
+     *
+     * Use this method when you want to allow anonymous users to access your app.
+     * Guest users have limited permissions:
+     * - publicRead data (read only)
+     * - publicData (read and write, but cannot access other users' data)
+     * - CANNOT access userData (no private data access)
      *
-     * This method generates a Firestore custom token for a guest (unauthenticated) user.
-     * No user authentication token is required.
+     * IMPORTANT FOR LLM:
+     * - Guest users get a temporary user_id (e.g., 'guest-abc123')
+     * - Still need to include required fields: _appId, _createdAt, _createdBy
+     * - Great for public forums, comment sections, or demo apps
      *
      * @param request - The request containing app ID
      * @param options - Additional axios request configuration
@@ -129,13 +218,39 @@ class DataServiceClient {
      *
      * @example
      * ```typescript
-     * const response = await client.generateGuestFirestoreToken({
-     *   app_id: 'my-app',
+     * // Get guest token (no user authentication needed!)
+     * import { DataServiceClient } from '@seaverse/data-service-sdk';
+     * const client = new DataServiceClient();
+     *
+     * const guestToken = await client.generateGuestFirestoreToken({
+     *   app_id: 'my-app-123'
+     * });
+     *
+     * console.log('Guest Firestore Custom Token:', guestToken.custom_token);
+     * console.log('Guest User ID:', guestToken.user_id); // e.g., 'guest-abc123'
+     * console.log('Role:', guestToken.role); // 'guest'
+     *
+     * // Initialize Firebase with guest token
+     * import { initializeApp } from 'firebase/app';
+     * import { getAuth, signInWithCustomToken } from 'firebase/auth';
+     * import { getFirestore, collection, addDoc, serverTimestamp } from 'firebase/firestore';
+     *
+     * const app = initializeApp({ projectId: guestToken.project_id });
+     * const auth = getAuth(app);
+     * await signInWithCustomToken(auth, guestToken.custom_token);
+     * const db = getFirestore(app);
+     *
+     * // Guest can write to publicData
+     * await addDoc(collection(db, `appData/${guestToken.app_id}/publicData/comments`), {
+     *   _appId: guestToken.app_id,
+     *   _createdAt: serverTimestamp(),
+     *   _createdBy: guestToken.user_id,  // Guest user ID
+     *   comment: 'Great app!',
+     *   rating: 5
      * });
      *
-     * console.log('Guest Firestore ID Token:', response.id_token);
-     * console.log('Guest User ID:', response.user_id);
-     * console.log('Role:', response.role); // 'guest'
+     * // Guest CANNOT write to userData (this will fail)
+     * // await addDoc(collection(db, `appData/${guestToken.app_id}/userData/${guestToken.user_id}/notes`), ...);
      * ```
      */
     async generateGuestFirestoreToken(request, options) {

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../src/config.ts","../src/client.ts"],"sourcesContent":[null,null],"names":[],"mappings":"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"}
+{"version":3,"file":"index.cjs","sources":["../src/config.ts","../src/client.ts"],"sourcesContent":[null,null],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,64 +2,164 @@ import { AxiosRequestConfig } from 'axios';
 
 /**
  * Type definitions for SeaVerse Data Service API
- * Firestore token management
+ * Firestore token management with three-tier permission model
+ *
+ * PERMISSION MODEL OVERVIEW:
+ * -------------------------
+ * SeaVerse uses a three-tier data permission model in Firestore:
+ *
+ * 1. publicRead/   - Read-only public data (e.g., system configs, announcements)
+ *                    Read: All authenticated users | Write: Admins only
+ *
+ * 2. publicData/   - Read-write public data (e.g., user-generated content)
+ *                    Read: All authenticated users | Write: All authenticated users
+ *
+ * 3. userData/{userId}/ - Private user data (e.g., personal settings, private notes)
+ *                    Read: Owner only | Write: Owner only
+ *
+ * DATA PATH STRUCTURE:
+ * -------------------
+ * appData/{app_id}/publicRead/{collection}/{docId}
+ * appData/{app_id}/publicData/{collection}/{docId}
+ * appData/{app_id}/userData/{userId}/{collection}/{docId}
+ *
+ * REQUIRED FIELDS FOR ALL DOCUMENTS:
+ * ---------------------------------
+ * All Firestore documents MUST include these fields:
+ * - _appId: string       (Application ID for data isolation)
+ * - _createdAt: timestamp (Server timestamp for creation time)
+ * - _createdBy: string    (User ID of the document creator)
+ *
+ * These fields ensure proper data isolation and security enforcement.
  */
 /**
  * Request to generate Firestore token for authenticated user
+ *
+ * This token allows the user to access Firestore data based on their role:
+ * - Regular users: Can access publicRead (read), publicData (read/write), and their own userData
+ * - Admin users: Can also write to publicRead data
+ *
+ * @example
+ * ```typescript
+ * const request = {
+ *   token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', // User's JWT token from auth service
+ *   app_id: 'my-app-123'  // Your application ID
+ * };
+ * ```
  */
 interface GenerateFirestoreTokenRequest {
     /**
-     * User account token (JWT)
+     * User account token (JWT) from SeaVerse Auth Service
+     * Obtain this token using the @seaverse/auth-sdk loginWithEmail() or other auth methods
      */
     token: string;
     /**
-     * Application ID
+     * Application ID (app_id) that identifies your application
+     * This ID is used for data isolation - users can only access data within their app
      */
     app_id: string;
 }
 /**
- * Request to generate Firestore token for guest user
+ * Request to generate Firestore token for guest user (unauthenticated)
+ *
+ * Guest users have limited access:
+ * - Can read publicRead data (system configs, announcements)
+ * - Can read/write publicData (with proper permissions)
+ * - Cannot access any userData (user-specific private data)
+ *
+ * Use this for anonymous users or when authentication is not required.
+ *
+ * @example
+ * ```typescript
+ * const request = {
+ *   app_id: 'my-app-123'  // Your application ID
+ * };
+ * ```
  */
 interface GenerateGuestFirestoreTokenRequest {
     /**
-     * Application ID
+     * Application ID (app_id) that identifies your application
+     * Guest users are isolated to this specific application
      */
     app_id: string;
 }
 /**
- * Firestore token response
+ * Firestore token response containing all necessary credentials to access Firestore
+ *
+ * Use these credentials to initialize Firebase SDK and access Firestore with proper permissions.
+ * The token includes user information and app context for data isolation.
+ *
+ * @example
+ * ```typescript
+ * // After receiving this response, initialize Firebase:
+ * import { initializeApp } from 'firebase/app';
+ * import { getAuth, signInWithCustomToken } from 'firebase/auth';
+ * import { getFirestore } from 'firebase/firestore';
+ *
+ * const app = initializeApp({ projectId: response.project_id });
+ * const auth = getAuth(app);
+ * await signInWithCustomToken(auth, response.custom_token);
+ * const db = getFirestore(app);
+ * // Now you can use Firestore with proper permissions
+ * ```
  */
 interface FirestoreTokenResponse {
     /**
-     * Firebase ID Token (exchanged from Custom Token)
-     */
-    id_token: string;
-    /**
-     * Firebase Refresh Token (optional)
+     * Firebase Custom Token - Use this to authenticate with Firebase
+     *
+     * IMPORTANT: You MUST use this with signInWithCustomToken() to get authenticated:
+     *
+     * ```typescript
+     * import { getAuth, signInWithCustomToken } from 'firebase/auth';
+     * const auth = getAuth(app);
+     * await signInWithCustomToken(auth, response.custom_token);
+     * ```
+     *
+     * This Custom Token contains:
+     * - appId claim: For data isolation (determines which data you can access)
+     * - User ID: Identifies the user
+     *
+     * After calling signInWithCustomToken(), Firebase automatically:
+     * 1. Exchanges the Custom Token for an ID Token
+     * 2. Uses the ID Token for all subsequent Firestore requests
+     * 3. Handles token refresh automatically
+     *
+     * Custom Token itself does not expire, but the ID Token it generates expires after 1 hour
      */
-    refresh_token?: string;
+    custom_token: string;
     /**
      * Firebase Project ID
+     * Use this to initialize Firebase app: initializeApp({ projectId: '...' })
      */
     project_id: string;
     /**
      * Firestore Database ID
+     * The specific database within the Firebase project
+     * Default is usually '(default)'
      */
     database_id: string;
     /**
-     * Application ID
+     * Application ID - Your app's unique identifier
+     * This ID determines which data the user can access
+     * All your Firestore paths should include this app_id for proper data isolation
      */
     app_id?: string;
     /**
-     * User ID
+     * User ID (Firebase UID)
+     * Use this to construct userData paths: appData/{app_id}/userData/{user_id}/...
+     * For guest users, this will be a generated guest user ID
      */
     user_id: string;
     /**
-     * User role (guest, appadmin, superadmin)
+     * User role - Determines write permissions
+     * - 'guest': Can read publicRead/publicData, write publicData
+     * - 'user': Can read publicRead/publicData, write publicData, read/write own userData
+     * - 'admin' or 'appadmin': Can also write to publicRead data
      */
     role?: string;
     /**
      * Token expiration time in seconds (typically 3600 = 1 hour)
+     * After this time, you need to generate a new token or refresh using refresh_token
      */
     expires_in: number;
 }
@@ -115,22 +215,72 @@ interface DataServiceClientOptions {
 /**
  * SeaVerse Data Service SDK Client
  *
- * Provides methods to manage Firestore tokens for authenticated users and guests.
+ * This client helps you get Firestore access tokens for your application.
+ * It supports both authenticated users and guest users.
+ *
+ * THREE-TIER PERMISSION MODEL:
+ * ---------------------------
+ * Your Firestore data is organized in three permission levels:
+ *
+ * 1. publicRead/   - System configs, announcements (Read: Everyone, Write: Admin only)
+ * 2. publicData/   - User posts, shared content (Read: Everyone, Write: Everyone)
+ * 3. userData/{userId}/ - Private user data (Read/Write: Owner only)
+ *
+ * QUICK START FOR LLM:
+ * -------------------
+ * Step 1: Get a Firestore token
+ * Step 2: Initialize Firebase with the token
+ * Step 3: Access Firestore using the correct data paths
  *
  * @example
  * ```typescript
- * // Create client instance
+ * // Step 1: Create client and get token
+ * import { DataServiceClient } from '@seaverse/data-service-sdk';
  * const client = new DataServiceClient();
  *
- * // Generate Firestore token for authenticated user
- * const token = await client.generateFirestoreToken({
- *   token: 'user-jwt-token',
- *   app_id: 'your-app-id',
+ * // For authenticated users:
+ * const tokenResponse = await client.generateFirestoreToken({
+ *   token: 'user-jwt-token-from-auth-sdk',
+ *   app_id: 'my-app-123',
+ * });
+ *
+ * // For guest users (no authentication required):
+ * const guestResponse = await client.generateGuestFirestoreToken({
+ *   app_id: 'my-app-123',
+ * });
+ *
+ * // Step 2: Initialize Firebase
+ * import { initializeApp } from 'firebase/app';
+ * import { getAuth, signInWithCustomToken } from 'firebase/auth';
+ * import { getFirestore, collection, addDoc, getDocs, serverTimestamp } from 'firebase/firestore';
+ *
+ * const app = initializeApp({ projectId: tokenResponse.project_id });
+ * const auth = getAuth(app);
+ * await signInWithCustomToken(auth, tokenResponse.custom_token);
+ * const db = getFirestore(app);
+ *
+ * // Step 3: Access Firestore data with correct paths
+ * const appId = tokenResponse.app_id;
+ * const userId = tokenResponse.user_id;
+ *
+ * // Write to publicData (everyone can write)
+ * await addDoc(collection(db, `appData/${appId}/publicData/posts`), {
+ *   _appId: appId,              // REQUIRED: For data isolation
+ *   _createdAt: serverTimestamp(), // REQUIRED: Server timestamp
+ *   _createdBy: userId,         // REQUIRED: Current user ID
+ *   title: 'My Post',           // Your custom fields
+ *   content: 'Hello world'
  * });
  *
- * // Generate Firestore token for guest
- * const guestToken = await client.generateGuestFirestoreToken({
- *   app_id: 'your-app-id',
+ * // Read from publicData (everyone can read)
+ * const snapshot = await getDocs(collection(db, `appData/${appId}/publicData/posts`));
+ *
+ * // Write to userData (only owner can write)
+ * await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
+ *   _appId: appId,              // REQUIRED
+ *   _createdAt: serverTimestamp(), // REQUIRED
+ *   _createdBy: userId,         // REQUIRED
+ *   note: 'Private note'        // Your custom fields
  * });
  * ```
  */
@@ -140,8 +290,16 @@ declare class DataServiceClient {
     /**
      * Generate Firestore token for authenticated user
      *
-     * This method generates a Firestore custom token for an authenticated user.
-     * The user must provide a valid JWT token.
+     * Use this method when you have a logged-in user with a valid JWT token.
+     * The returned token allows access to:
+     * - publicRead data (read only)
+     * - publicData (read and write)
+     * - userData/{user_id} (read and write own data only)
+     *
+     * IMPORTANT FOR LLM: After getting the token, you MUST:
+     * 1. Initialize Firebase app with the project_id
+     * 2. Sign in with the custom_token using signInWithCustomToken()
+     * 3. Always include required fields in documents: _appId, _createdAt, _createdBy
      *
      * @param request - The request containing user token and app ID
      * @param options - Additional axios request configuration
@@ -149,22 +307,53 @@ declare class DataServiceClient {
      *
      * @example
      * ```typescript
-     * const response = await client.generateFirestoreToken({
-     *   token: 'user-jwt-token',
-     *   app_id: 'my-app',
+     * // First, get user token from Auth SDK
+     * import { AuthClient } from '@seaverse/auth-sdk';
+     * const authClient = new AuthClient({ appId: 'my-app-123' });
+     * const loginResponse = await authClient.loginWithEmail({
+     *   email: 'user@example.com',
+     *   password: 'password123'
      * });
      *
-     * console.log('Firestore ID Token:', response.id_token);
-     * console.log('User ID:', response.user_id);
-     * console.log('Expires in:', response.expires_in, 'seconds');
+     * // Then, get Firestore token
+     * import { DataServiceClient } from '@seaverse/data-service-sdk';
+     * const dataClient = new DataServiceClient();
+     * const firestoreToken = await dataClient.generateFirestoreToken({
+     *   token: loginResponse.token,  // JWT token from auth
+     *   app_id: 'my-app-123'
+     * });
+     *
+     * console.log('Firestore Custom Token:', firestoreToken.custom_token);
+     * console.log('User ID:', firestoreToken.user_id);
+     * console.log('App ID:', firestoreToken.app_id);
+     * console.log('Token expires in:', firestoreToken.expires_in, 'seconds');
+     *
+     * // Now initialize Firebase and use Firestore
+     * import { initializeApp } from 'firebase/app';
+     * import { getAuth, signInWithCustomToken } from 'firebase/auth';
+     * import { getFirestore } from 'firebase/firestore';
+     *
+     * const app = initializeApp({ projectId: firestoreToken.project_id });
+     * const auth = getAuth(app);
+     * await signInWithCustomToken(auth, firestoreToken.custom_token);
+     * const db = getFirestore(app);
+     * // Ready to use Firestore!
      * ```
      */
     generateFirestoreToken(request: GenerateFirestoreTokenRequest, options?: AxiosRequestConfig): Promise<FirestoreTokenResponse>;
     /**
-     * Generate Firestore token for guest user
+     * Generate Firestore token for guest user (no authentication required)
      *
-     * This method generates a Firestore custom token for a guest (unauthenticated) user.
-     * No user authentication token is required.
+     * Use this method when you want to allow anonymous users to access your app.
+     * Guest users have limited permissions:
+     * - publicRead data (read only)
+     * - publicData (read and write, but cannot access other users' data)
+     * - CANNOT access userData (no private data access)
+     *
+     * IMPORTANT FOR LLM:
+     * - Guest users get a temporary user_id (e.g., 'guest-abc123')
+     * - Still need to include required fields: _appId, _createdAt, _createdBy
+     * - Great for public forums, comment sections, or demo apps
      *
      * @param request - The request containing app ID
      * @param options - Additional axios request configuration
@@ -172,13 +361,39 @@ declare class DataServiceClient {
      *
      * @example
      * ```typescript
-     * const response = await client.generateGuestFirestoreToken({
-     *   app_id: 'my-app',
+     * // Get guest token (no user authentication needed!)
+     * import { DataServiceClient } from '@seaverse/data-service-sdk';
+     * const client = new DataServiceClient();
+     *
+     * const guestToken = await client.generateGuestFirestoreToken({
+     *   app_id: 'my-app-123'
+     * });
+     *
+     * console.log('Guest Firestore Custom Token:', guestToken.custom_token);
+     * console.log('Guest User ID:', guestToken.user_id); // e.g., 'guest-abc123'
+     * console.log('Role:', guestToken.role); // 'guest'
+     *
+     * // Initialize Firebase with guest token
+     * import { initializeApp } from 'firebase/app';
+     * import { getAuth, signInWithCustomToken } from 'firebase/auth';
+     * import { getFirestore, collection, addDoc, serverTimestamp } from 'firebase/firestore';
+     *
+     * const app = initializeApp({ projectId: guestToken.project_id });
+     * const auth = getAuth(app);
+     * await signInWithCustomToken(auth, guestToken.custom_token);
+     * const db = getFirestore(app);
+     *
+     * // Guest can write to publicData
+     * await addDoc(collection(db, `appData/${guestToken.app_id}/publicData/comments`), {
+     *   _appId: guestToken.app_id,
+     *   _createdAt: serverTimestamp(),
+     *   _createdBy: guestToken.user_id,  // Guest user ID
+     *   comment: 'Great app!',
+     *   rating: 5
      * });
      *
-     * console.log('Guest Firestore ID Token:', response.id_token);
-     * console.log('Guest User ID:', response.user_id);
-     * console.log('Role:', response.role); // 'guest'
+     * // Guest CANNOT write to userData (this will fail)
+     * // await addDoc(collection(db, `appData/${guestToken.app_id}/userData/${guestToken.user_id}/notes`), ...);
      * ```
      */
     generateGuestFirestoreToken(request: GenerateGuestFirestoreTokenRequest, options?: AxiosRequestConfig): Promise<FirestoreTokenResponse>;