@seaverse/data-service-sdk 0.2.0 → 0.3.0

package/README.md

@@ -69,7 +69,7 @@ const firestoreToken = await dataClient.generateFirestoreToken({
 // Step 3: Initialize Firebase
 const app = initializeApp({ projectId: firestoreToken.project_id });
 const auth = getAuth(app);
-await signInWithCustomToken(auth, firestoreToken.id_token);
+await signInWithCustomToken(auth, firestoreToken.custom_token);
 const db = getFirestore(app);
 
 // Step 4: Use Firestore with proper paths
@@ -118,7 +118,7 @@ const guestToken = await dataClient.generateGuestFirestoreToken({
 // Step 2: Initialize Firebase
 const app = initializeApp({ projectId: guestToken.project_id });
 const auth = getAuth(app);
-await signInWithCustomToken(auth, guestToken.id_token);
+await signInWithCustomToken(auth, guestToken.custom_token);
 const db = getFirestore(app);
 
 // Step 3: Guest can write to publicData
@@ -189,8 +189,7 @@ interface GenerateFirestoreTokenRequest {
 
 ```typescript
 interface FirestoreTokenResponse {
-  id_token: string;         // Firebase ID Token for signInWithCustomToken()
-  refresh_token?: string;   // Firebase Refresh Token (optional)
+  custom_token: string;     // Firebase Custom Token - use with signInWithCustomToken()
   project_id: string;       // Firebase Project ID for initializeApp()
   database_id: string;      // Firestore Database ID
   app_id?: string;          // Application ID (use in Firestore paths)
@@ -208,7 +207,7 @@ const firestoreToken = await client.generateFirestoreToken({
   app_id: 'my-app-123'
 });
 
-console.log('Token:', firestoreToken.id_token);
+console.log('Custom Token:', firestoreToken.custom_token);
 console.log('User ID:', firestoreToken.user_id);
 console.log('App ID:', firestoreToken.app_id);
 ```
@@ -243,7 +242,7 @@ const guestToken = await client.generateGuestFirestoreToken({
   app_id: 'my-app-123'
 });
 
-console.log('Guest Token:', guestToken.id_token);
+console.log('Guest Custom Token:', guestToken.custom_token);
 console.log('Guest User ID:', guestToken.user_id);
 console.log('Role:', guestToken.role); // 'guest'
 ```
@@ -451,7 +450,7 @@ async function completeExample() {
   // 3. Initialize Firebase
   const app = initializeApp({ projectId: firestoreToken.project_id });
   const auth = getAuth(app);
-  await signInWithCustomToken(auth, firestoreToken.id_token);
+  await signInWithCustomToken(auth, firestoreToken.custom_token);
   const db = getFirestore(app);
 
   const userId = firestoreToken.user_id;

package/dist/index.cjs

@@ -65,7 +65,7 @@ const ENDPOINTS = {
  *
  * const app = initializeApp({ projectId: tokenResponse.project_id });
  * const auth = getAuth(app);
- * await signInWithCustomToken(auth, tokenResponse.id_token);
+ * await signInWithCustomToken(auth, tokenResponse.custom_token);
  * const db = getFirestore(app);
  *
  * // Step 3: Access Firestore data with correct paths
@@ -146,7 +146,7 @@ class DataServiceClient {
      *
      * IMPORTANT FOR LLM: After getting the token, you MUST:
      * 1. Initialize Firebase app with the project_id
-     * 2. Sign in with the id_token using signInWithCustomToken()
+     * 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
@@ -171,7 +171,7 @@ class DataServiceClient {
      *   app_id: 'my-app-123'
      * });
      *
-     * console.log('Firestore ID Token:', firestoreToken.id_token);
+     * 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');
@@ -183,7 +183,7 @@ class DataServiceClient {
      *
      * const app = initializeApp({ projectId: firestoreToken.project_id });
      * const auth = getAuth(app);
-     * await signInWithCustomToken(auth, firestoreToken.id_token);
+     * await signInWithCustomToken(auth, firestoreToken.custom_token);
      * const db = getFirestore(app);
      * // Ready to use Firestore!
      * ```
@@ -226,7 +226,7 @@ class DataServiceClient {
      *   app_id: 'my-app-123'
      * });
      *
-     * console.log('Guest Firestore ID Token:', guestToken.id_token);
+     * 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'
      *
@@ -237,7 +237,7 @@ class DataServiceClient {
      *
      * const app = initializeApp({ projectId: guestToken.project_id });
      * const auth = getAuth(app);
-     * await signInWithCustomToken(auth, guestToken.id_token);
+     * await signInWithCustomToken(auth, guestToken.custom_token);
      * const db = getFirestore(app);
      *
      * // Guest can write to publicData

package/dist/index.d.ts

@@ -98,24 +98,35 @@ interface GenerateGuestFirestoreTokenRequest {
  *
  * const app = initializeApp({ projectId: response.project_id });
  * const auth = getAuth(app);
- * await signInWithCustomToken(auth, response.id_token);
+ * 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)
-     * Use this with signInWithCustomToken() to authenticate with Firebase
-     * This token expires after the time specified in expires_in (typically 1 hour)
-     */
-    id_token: string;
-    /**
-     * Firebase Refresh Token (optional)
-     * Used to refresh the id_token when it expires
-     * May not be present for guest users
+     * 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: '...' })
@@ -245,7 +256,7 @@ interface DataServiceClientOptions {
  *
  * const app = initializeApp({ projectId: tokenResponse.project_id });
  * const auth = getAuth(app);
- * await signInWithCustomToken(auth, tokenResponse.id_token);
+ * await signInWithCustomToken(auth, tokenResponse.custom_token);
  * const db = getFirestore(app);
  *
  * // Step 3: Access Firestore data with correct paths
@@ -287,7 +298,7 @@ declare class DataServiceClient {
      *
      * IMPORTANT FOR LLM: After getting the token, you MUST:
      * 1. Initialize Firebase app with the project_id
-     * 2. Sign in with the id_token using signInWithCustomToken()
+     * 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
@@ -312,7 +323,7 @@ declare class DataServiceClient {
      *   app_id: 'my-app-123'
      * });
      *
-     * console.log('Firestore ID Token:', firestoreToken.id_token);
+     * 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');
@@ -324,7 +335,7 @@ declare class DataServiceClient {
      *
      * const app = initializeApp({ projectId: firestoreToken.project_id });
      * const auth = getAuth(app);
-     * await signInWithCustomToken(auth, firestoreToken.id_token);
+     * await signInWithCustomToken(auth, firestoreToken.custom_token);
      * const db = getFirestore(app);
      * // Ready to use Firestore!
      * ```
@@ -358,7 +369,7 @@ declare class DataServiceClient {
      *   app_id: 'my-app-123'
      * });
      *
-     * console.log('Guest Firestore ID Token:', guestToken.id_token);
+     * 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'
      *
@@ -369,7 +380,7 @@ declare class DataServiceClient {
      *
      * const app = initializeApp({ projectId: guestToken.project_id });
      * const auth = getAuth(app);
-     * await signInWithCustomToken(auth, guestToken.id_token);
+     * await signInWithCustomToken(auth, guestToken.custom_token);
      * const db = getFirestore(app);
      *
      * // Guest can write to publicData

package/dist/index.js

@@ -63,7 +63,7 @@ const ENDPOINTS = {
  *
  * const app = initializeApp({ projectId: tokenResponse.project_id });
  * const auth = getAuth(app);
- * await signInWithCustomToken(auth, tokenResponse.id_token);
+ * await signInWithCustomToken(auth, tokenResponse.custom_token);
  * const db = getFirestore(app);
  *
  * // Step 3: Access Firestore data with correct paths
@@ -144,7 +144,7 @@ class DataServiceClient {
      *
      * IMPORTANT FOR LLM: After getting the token, you MUST:
      * 1. Initialize Firebase app with the project_id
-     * 2. Sign in with the id_token using signInWithCustomToken()
+     * 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
@@ -169,7 +169,7 @@ class DataServiceClient {
      *   app_id: 'my-app-123'
      * });
      *
-     * console.log('Firestore ID Token:', firestoreToken.id_token);
+     * 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');
@@ -181,7 +181,7 @@ class DataServiceClient {
      *
      * const app = initializeApp({ projectId: firestoreToken.project_id });
      * const auth = getAuth(app);
-     * await signInWithCustomToken(auth, firestoreToken.id_token);
+     * await signInWithCustomToken(auth, firestoreToken.custom_token);
      * const db = getFirestore(app);
      * // Ready to use Firestore!
      * ```
@@ -224,7 +224,7 @@ class DataServiceClient {
      *   app_id: 'my-app-123'
      * });
      *
-     * console.log('Guest Firestore ID Token:', guestToken.id_token);
+     * 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'
      *
@@ -235,7 +235,7 @@ class DataServiceClient {
      *
      * const app = initializeApp({ projectId: guestToken.project_id });
      * const auth = getAuth(app);
-     * await signInWithCustomToken(auth, guestToken.id_token);
+     * await signInWithCustomToken(auth, guestToken.custom_token);
      * const db = getFirestore(app);
      *
      * // Guest can write to publicData

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seaverse/data-service-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SDK for SeaVerse Data Service - Firestore token management with three-tier permission model",
   "type": "module",
   "main": "dist/index.cjs",