### Example Chatbot Context Configuration

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-genai-chatbot/PREINSTALL.md

This is an example of context configuration for the chatbot. Providing context helps define the chatbot's persona and behavior, such as acting as a travel guide.

```text
I want you to act as a travel guide. I will ask you questions about various travel destinations, and you will describe those destinations and give me suggestions on places to visit.
```

--------------------------------

### Copy Environment Configuration Example

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

Copy the example environment file to create your own configuration. This file is used to set up test-specific variables.

```bash
cp __tests__/e2e/.env.e2e.test.example __tests__/e2e/.env.e2e.test
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

Install all necessary Node.js packages for the project using npm. This should be run after cloning the repository.

```bash
npm install
```

--------------------------------

### Example Prompt for Star Rating Prediction

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-multimodal-genai/PREINSTALL.md

This example demonstrates how to structure a prompt for predicting star ratings from review text. It includes examples of direct text and a placeholder for dynamic review text substitution using handlebars.

```text
Provide a star rating from 1-5 of the following review text: “This is a truly incredible water bottle, I keep it with me all the time when I’m traveling and it has never let me down.”
5

Provide a star rating from 1-5 of the following review text: “ I really enjoyed the water bottle, I just wish they carried this in a larger size as I go for long hikes. But overall the aesthetic, manufacturing, and functional design are great for what I needed.”
4

Provide a star rating from 1-5 of the following review text: “ The water bottle was fine, although the design was a bit lacking and could be improved.”
3

Provide a star rating from 1-5 of the following review text: “ Please don’t get this water bottle, there are major design flaws, for example the cap doesn’t screw on fully so water leaks into my backpack all the time.”
1

Provide a star rating from 1-5 of the following review text: “{{review_text}}”
```

--------------------------------

### Example Prompt for Star Rating Prediction

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-multimodal-genai/README.md

This example demonstrates how to structure a prompt for predicting star ratings from review text. It includes examples of few-shot learning and uses a handlebars variable `{{review_text}}` for dynamic input from Firestore documents.

```text
Provide a star rating from 1-5 of the following review text: “This is a truly incredible water bottle, I keep it with me all the time when I’m traveling and it has never let me down.”
5

Provide a star rating from 1-5 of the following review text: “ I really enjoyed the water bottle, I just wish they carried this in a larger size as I go for long hikes. But overall the aesthetic, manufacturing, and functional design are great for what I needed.”
4

Provide a star rating from 1-5 of the following review text: “The water bottle was fine, although the design was a bit lacking and could be improved.”
3

Provide a star rating from 1-5 of the following review text: “Please don’t get this water bottle, there are major design flaws, for example the cap doesn’t screw on fully so water leaks into my backpack all the time.”
1

Provide a star rating from 1-5 of the following review text: “{{review_text}}”
```

--------------------------------

### Install Dependencies for Firebase Extension

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/AGENTS.md

Use this command to install project dependencies within an extension's functions directory. Ensure you are in the correct extension directory.

```bash
cd <extension>/functions
npm install
```

--------------------------------

### Run All Firebase Extension Tests

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/AGENTS.md

Start the Firebase emulator and run tests for all extensions in the monorepo. This command is executed from the project's root directory.

```bash
npm run test
```

--------------------------------

### Example Message Document Structure

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-genai-chatbot/PREINSTALL.md

This is an example of the structure for a message document stored in Cloud Firestore. The 'prompt' field contains the user's input.

```json
{
  prompt: "What is the best museum to visit in Barcelona, Spain?"
}
```

--------------------------------

### Example Message Document Structure

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-genai-chatbot/README.md

Illustrates the expected format for message documents in Firestore, which the extension listens to for new messages.

```json
{
  "prompt": "What is the best museum to visit in Barcelona, Spain?"
}
```

--------------------------------

### GitHub Actions CI for E2E Tests

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

This workflow automates E2E tests on push or pull request events. It checks out code, sets up Node.js, installs dependencies, builds the project, and runs E2E tests using environment variables for authentication and configuration.

```yaml
name: E2E Tests
on:
  push:
    branches: [main]
  pull_request:

jobs:
  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Run E2E tests
        env:
          E2E_PROJECT_ID: ${{ secrets.E2E_PROJECT_ID }}
          E2E_LOCATION: us-central1
          E2E_BIGQUERY_DATASET_LOCATION: US
          GOOGLE_APPLICATION_CREDENTIALS: /tmp/gcp-key.json
        run: |
          echo '${{ secrets.GCP_SA_KEY }}' > /tmp/gcp-key.json
          npm run test:e2e:ci
```

--------------------------------

### Run Local Tests for Firebase Extensions

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/AGENTS.md

Execute tests for all Firebase extensions without starting the emulator. This requires the emulator to be already running.

```bash
npm run test:local
```

--------------------------------

### Authenticate with Application Default Credentials

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

Log in with your user credentials and set the project for local development. This uses `gcloud` for authentication.

```bash
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
```

--------------------------------

### Create Artifact Registry Repository

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-incremental-capture/POSTINSTALL.md

Create a Docker repository in Artifact Registry to store Dataflow Flex Template images. The --async flag allows the command to return immediately.

```bash
gcloud artifacts repositories create ${param:EXT_INSTANCE_ID} \
  --repository-format=docker \
  --location=${param:LOCATION} \
  --project=${param:PROJECT_ID} \
  --async
```

--------------------------------

### Build the Project

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

Compile TypeScript code and prepare the project for execution. This command is typically run before testing or deployment.

```bash
npm run build
```

--------------------------------

### Example Custom Embedding Function

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-vector-search/POSTINSTALL.md

This JavaScript example demonstrates a Firebase HTTP function that can be used as a custom embedding endpoint. It expects a POST request with a JSON body containing a 'batch' of strings and returns an array of embeddings. Ensure the function handles POST requests and validates input.

```javascript
const {https} = require('firebase-functions');
const {logger} = require('firebase-functions');

// This function is triggered on HTTP requests
exports.processBatch = https.onRequest((request, response) => {
  // Log the incoming request
  logger.info('Processing batch', {structuredData: true});

  // Ensure the request is a POST request
  if (request.method !== 'POST') {
    // Respond with 405 Method Not Allowed if not a POST request
    response.status(405).send('Only POST requests are accepted');
    return;
  }

  try {
    // Parse the request body
    const {batch} = request.body;

    // Validate the batch input
    if (!Array.isArray(batch)) {
      response
        .status(400)
        .send('Invalid input: batch must be an array of strings.');
      return;
    }

    // Map each string in the batch to [1, 0] if it contains "cat", [0, 1] otherwise
    const embeddings = batch.map(item =>
      item.includes('cat') ? [1, 0] : [0, 1]
    );

    // Send the response with the embeddings array
    response.send({embeddings});
  } catch (error) {
    // Handle any errors that might occur
    logger.error('Error processing request', {error});
    response
      .status(500)
      .send('An error occurred while processing the request.');
  }
});
```

--------------------------------

### Create Firestore Database Instance

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-incremental-capture/PREINSTALL.md

Use this script to create a new Firestore database instance if one does not already exist. This is required for the extension to perform restorations.

```bash
gcloud alpha firestore databases create \
    --database=DATABASE_ID \
    --location=LOCATION \
    --type=firestore-native \
    --project=PROJECT_ID
```

--------------------------------

### Manually List BigQuery Datasets

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

List BigQuery datasets within a specific project to identify test resources that may need manual cleanup. Use `bq ls` command.

```bash
bq ls --project_id=YOUR_PROJECT_ID | grep e2e_test_
```

--------------------------------

### Build Dataflow Flex Template

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-incremental-capture/POSTINSTALL.md

Build the Dataflow Flex Template using the downloaded JAR file. This command specifies the output Cloud Storage location, the Docker image path, and the main class for the Java SDK.

```bash
gcloud dataflow flex-template build gs://${param:PROJECT_ID}.appspot.com/${param:EXT_INSTANCE_ID}-dataflow-restore \
    --image-gcr-path ${param:LOCATION}-docker.pkg.dev/${param:PROJECT_ID}/${param:EXT_INSTANCE_ID}/dataflow/restore:latest \
    --sdk-language JAVA \
    --flex-template-base-image JAVA11 \
    --jar /path/to/restore-firestore.jar \
    --env FLEX_TEMPLATE_JAVA_MAIN_CLASS="com.pipeline.RestorationPipeline" \
    --project ${param:PROJECT_ID}
```

--------------------------------

### Trigger Firestore Restoration Job

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-incremental-capture/POSTINSTALL.md

Trigger a Firestore restoration job using a curl command. This example shows how to run a restoration from one hour ago, including authentication and content type headers.

```bash
curl -m 70 -X POST https://us-central1-${PROJECT_ID}.cloudfunctions.net/ext-firestore-incremental-capture-onHttpRunRestoration \
-H "Authorization: bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json" \
-d "{\"timestamp\":$(date -u -v-1H +%s)}"
```

--------------------------------

### Manually List Pub/Sub Topics

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

List Pub/Sub topics in a project to identify test-related topics for manual cleanup. Use `gcloud pubsub topics list` command.

```bash
gcloud pubsub topics list --project=YOUR_PROJECT_ID | grep e2e-test-
```

--------------------------------

### Client-side Integration for Text Similarity Search

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-semantic-search/POSTINSTALL.md

Integrate text similarity search into your client application using Firebase SDK. This example shows how to call the callable function and process the results to fetch document IDs.

```javascript
import firebase from "firebase";
import { getFunctions, httpsCallable } from "firebase/functions";

const functions = getFunctions();
const search = httpsCallable(functions, `ext-${param:EXT_INSTANCE_ID}-queryIndex`);

// run search
await search({ query: searchQuery })
  .then(async (result) => {
    // get results
    const { nearestNeighbours } = result.data;
    const paths  = nearestNeighbours.neighbours.map($ => $.datapoint.datapointId);

    // fetch documents from Firestore using the ids...
});
```

--------------------------------

### Set Service Account Credentials

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

Export the path to your service account key JSON file to authenticate for CI/CD. Recommended for automated environments.

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
```

--------------------------------

### Compile JAR for Dataflow Deployment

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-incremental-capture-pipeline/README.md

Compile the project into a JAR file suitable for running on Dataflow. This command skips tests to speed up the build process.

```bash
mvn clean package -DskipTests -Dexec.mainClass=com.pipeline.RestorationPipeline
```

--------------------------------

### Run All E2E Tests Locally

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

Execute all end-to-end tests in a local environment. This command uses the configuration defined in the `.env.e2e.test` file.

```bash
npm run test:e2e:local
```

--------------------------------

### Create a Secondary Firestore Database

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-incremental-capture/POSTINSTALL.md

Use this command to create a new secondary Firestore database. Ensure you replace DATABASE_ID, LOCATION, and PROJECT_ID with your specific values.

```bash
gcloud alpha firestore databases create --database=DATABASE_ID --location=LOCATION --type=firestore-native --project=${param:PROJECT_ID}
```

--------------------------------

### Compile All Firebase Extensions

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/AGENTS.md

Build all extensions within the monorepo using Lerna. This command is run from the root directory of the project.

```bash
npm run compile
```

--------------------------------

### Debug Pipeline Locally with DirectRunner

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-incremental-capture-pipeline/README.md

Use this command to debug the restoration pipeline locally. Ensure your Cloud Storage bucket name is correctly formatted, especially if provisioned after September 30, 2024.

```bash
mvn compile exec:java \
    -Dexec.mainClass=com.pipeline.RestorationPipeline \
    -Dexec.args='--timestamp=1697740800 --firestoreCollectionId="test" --firestoreDb="test" --tempLocation="gs://PROJECT_ID.appspot.com" --project="PROJECT_ID"'
```

--------------------------------

### Run Specific E2E Test Suites Locally

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

Execute specific subsets of end-to-end tests. You can filter by test suite name or use flags like `--verbose` for detailed output.

```bash
npm run test:e2e:local -- reconfiguration
npm run test:e2e:local -- --verbose
npm run test:e2e:local -- -t "should update query without affecting schedule"
```

--------------------------------

### Common Resource Already Exists Error

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

This error occurs when attempting to create a resource that already exists, like a BigQuery dataset. Clean up any orphaned resources from previous test runs or implement logic to use unique resource names.

```text
Error: Dataset e2e_test_xyz already exists
```

--------------------------------

### Callable Function Query Argument Structure

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-vector-search/POSTINSTALL.md

This is a sample argument structure for the callable function, demonstrating how to include a query string, an optional limit, and prefilter conditions. Prefilters require a composite index.

```json
{
    "query": "my query",
    "limit": 4,
    "prefilters": [
        {
            "field": "age",
            "operator": "==",
            "value": 30
        }
    ]
}

```

--------------------------------

### Configure Docker for Artifact Registry

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-incremental-capture/POSTINSTALL.md

Configure your Docker client to authenticate with Artifact Registry. This command sets up the necessary credentials for pushing and pulling images.

```bash
gcloud auth configure-docker ${param:LOCATION}-docker.pkg.dev
```

--------------------------------

### Enable Debug Logging for E2E Tests

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

Run tests with the `DEBUG` environment variable set to `*` to enable detailed logging. This is useful for diagnosing issues.

```bash
DEBUG=* npm run test:e2e:local
```

--------------------------------

### Generate README for Firebase Extension

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/AGENTS.md

Regenerate the README.md file for a Firebase extension using its extension.yaml manifest and PREINSTALL.md. This command should be run from the functions directory.

```bash
cd <extension>/functions
npm run generate-readme
```

--------------------------------

### Run E2E Tests in CI Environment

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

Execute end-to-end tests in a Continuous Integration environment. This command is optimized for CI/CD pipelines.

```bash
npm run test:e2e:ci
```

--------------------------------

### Client Integration for Reverse Image Search

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/storage-reverse-image-search/POSTINSTALL.md

This JavaScript snippet demonstrates how to initialize Firebase, authenticate a user, and call a Cloud Function for reverse image search. Ensure Firebase project configuration and authentication details are correctly set.

```javascript
import { initializeApp } from "firebase/app";
import { getAuth, signInWithEmailAndPassword } from "firebase/auth";
import { getFunctions, httpsCallable } from "firebase/functions";

// Firebase project configuration
const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_PROJECT_ID.appspot.com",
  messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
  appId: "YOUR_APP_ID"
};

// Firebase Auth credentials
const email = "user@example.com";
const password = "password";

// Query payload
const queryData = {
  query: [
    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", // base64 encoded image
  ],
};

// Main function to authenticate and call Firebase extension
async function callFunction() {
  try {
    console.log("Initializing Firebase...");
    const app = initializeApp(firebaseConfig);

    console.log("Authenticating user...");
    const auth = getAuth(app);
    const userCredential = await signInWithEmailAndPassword(
      auth,
      email,
      password
    );
    console.log(`✅ Logged in as: ${userCredential.user.email}`);

    console.log("Getting Cloud Function reference...");
    const functions = getFunctions(app);
    const search = httpsCallable(functions, `ext-${param:EXT_INSTANCE_ID}-queryIndex`);

    console.log("Calling the search function with query data...");
    const result = await search(queryData);
    const { nearestNeighbors } = result.data.data;

    console.log("✅ Function call successful.");
    console.log("🔍 Nearest Neighbors Result:\n");

    nearestNeighbors.forEach((entry, i) => {
      console.log(`Result #${i + 1} - Query ID: ${entry.id}`);
      entry.neighbors.forEach((neighbor, j) => {
        const {datapointId} = neighbor.datapoint;
        const distance = neighbor.distance.toFixed(2);
        console.log(`  [${j + 1}] ${datapointId} (distance: ${distance})`);
      });
    });
  } catch (error) {
    console.error("❌ Error calling function:", error.message || error);
  }
}

callFunction();

```

--------------------------------

### Run Single Test with Maximum Verbosity and Handle Open Handles

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/functions/__tests__/e2e/README.md

Execute a single test with verbose output, detect open handles to prevent test hangs, and specify the test name. Useful for focused debugging.

```bash
npm run test:e2e:local -- --verbose --detectOpenHandles -t "test name"
```

--------------------------------

### Run Tests for Firebase Extension

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/AGENTS.md

Execute tests for a specific Firebase extension. Integration tests require the emulator to be running.

```bash
cd <extension>/functions
npm test
```

--------------------------------

### Listen for Latest Transfer Run Updates

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/bigquery-firestore-export/POSTINSTALL.md

Set up a real-time listener on the 'latest' document within a transfer config's runs subcollection. This allows the client application to receive immediate updates whenever a new transfer run completes.

```javascript
const latestRunId = null;
db.collection(`transferConfigs/${transferConfigId}/runs`)
  .doc('latest')
  .onSnapshot(doc => {
    if (!!doc.data()) {
      latestRunId = doc.data().latestRunId;
    }
  });
```

--------------------------------

### Sample Response from Query Function

Source: https://github.com/googlecloudplatform/firebase-extensions/blob/main/firestore-semantic-search/POSTINSTALL.md

The response contains nearest neighbor information, including document IDs and distances. Note that the full data is not returned to adhere to security rules.

```json
{
  "nearestNeighbors": [
    {
      "id": "0",
      "neighbors": [
        {
          "datapoint": {
            "datapointId": "zVnAFpQQd6LDntOPhWlk",
            "crowdingTag": {
              "crowdingAttribute": "0"
            }
          },
          "distance": 0.40997931361198425
        },
        {
          "datapoint": {
            "datapointId": "VjdCBMgq939nUB846TZ2",
            "crowdingTag": {
              "crowdingAttribute": "0"
            }
          },
          "distance": 0.36510562896728516
        },
        ...
      ]
    }
  ]
}
```