extension.yaml

# Learn detailed information about the fields of an extension.yaml file in the docs:
# https://firebase.google.com/docs/extensions/alpha/ref-extension-yaml

# Identifier for your extension
name: firestore-algolia-search

# Follow semver versioning
version: 1.2.7

# Version of the Firebase Extensions specification
specVersion: v1beta

tags:
  [
    ai,
    search,
    semantic-search,
    vector-search,
    text-search
  ]

# Friendly display name for your extension (~3-5 words)
displayName: Search Firestore with Algolia

# Brief description of the task your extension performs (~1 sentence)
description: >-
  Enables full text search of your Cloud Firestore data with Algolia.

license: Apache-2.0  # https://spdx.org/licenses/

author:
  authorName: Algolia
  url: https://algolia.com

contributors:
  - authorName: Sajid Momin
    email: sajid.momin@algolia.com
    url: https://github.com/smomin

externalServices:
  - name: Algolia
    pricingUri: https://algolia.com/pricing

# Public URL for the source code of your extension
sourceUrl: https://github.com/algolia/firestore-algolia-search/tree/main

# Specify whether a paid-tier billing plan is required to use your extension.
# Learn more in the docs: https://firebase.google.com/docs/extensions/alpha/ref-extension-yaml#billing-required-field
billingRequired: true

# In an `apis` field, list any Google APIs (like Cloud Translation, BigQuery, etc.)
# required for your extension to operate.
# Learn more in the docs: https://firebase.google.com/docs/extensions/alpha/ref-extension-yaml#apis-field

# In a `roles` field, list any IAM access roles required for your extension to operate.
# Learn more in the docs: https://firebase.google.com/docs/extensions/alpha/ref-extension-yaml#roles-field
roles:
  - role: datastore.user
    reason: Allows this extension to access Cloud Firestore to read.

# In the `resources` field, list each of your extension's functions, including the trigger for each function.
# Learn more in the docs: https://firebase.google.com/docs/extensions/alpha/ref-extension-yaml#resources-field
resources:
  - name: executeIndexOperation
    type: firebaseextensions.v1beta.function
    description: >-
      Firestore document-triggered function that creates, updates, or deletes data in Algolia.
    properties: # LOCATION is a user-configured parameter value specified by the user
      # during installation.
      location: ${LOCATION}
      runtime: nodejs18
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/${DATABASE_ID}/documents/${COLLECTION_PATH}/{documentID}

  - name: executeFullIndexOperation
    type: firebaseextensions.v1beta.function
    description: Loads all the data from your FireStore database into Algolia
    properties:
      location: ${param:LOCATION}
      runtime: nodejs18
      availableMemoryMb: 1024
      timeout: 540s
      taskQueueTrigger: { }

# In the `params` field, set up your extension's user-configured parameters.
# Learn more in the docs: https://firebase.google.com/docs/extensions/alpha/ref-extension-yaml#params-field
params:
  - param: DATABASE_ID
    label: Database ID
    description: >
      Enter database that contains the collections that you want to monitor?
    default: '(default)'
    example: test
    required: true
    immutable: true

  - param: COLLECTION_PATH
    label: Collection Path
    description: >
      What is the path to the Cloud Firestore collection where the extension should monitor for changes?
    default: ''
    example: store
    validationRegex: "^[^/]+(/[^/]+/[^/]+)*$"
    validationErrorMessage: Firestore collection paths must be an odd number of segments separated by slashes, e.g. "movies/{id}/actors".
    required: true
    immutable: true

  - param: FIELDS
    label: Indexable Fields
    description: >
      This can be a comma separated list or left blank to index all fields.
      For performance reasons, [record size is limited](https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/in-depth/index-and-records-size-and-usage-limitations/#record-size-limits).
      If you're receiving errors that your records are too large, refer to the [reducing record size documentation](https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/how-to/reducing-object-size/).
    default: ''
    example: 'name,category,price,sales'
    required: false

  - param: FORCE_DATA_SYNC
    label: Force Data Sync
    description: >-
      The extension uses approaches to mitigate race conditions but it might not be a 100% fool proof.  This setting
      will make sure the function is using the latest data from Firestore by making another read call before processing
      and sending to Algolia.  NOTE: This will be a add to your usage of Firestore.
    type: select
    options:
      - label: No
        value: no
      - label: Yes
        value: yes
    default: no
    required: false

  - param: ALGOLIA_INDEX_NAME
    label: Algolia Index Name
    description: >-
      This is the name of the [Algolia index](https://www.algolia.com/doc/faq/basics/what-is-an-index/)
      where the records will be persisted.
      Refer to [naming your index](https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/#naming-your-index) for more information.
    type: string
    required: true

  - param: ALGOLIA_APP_ID
    label: Algolia Application Id
    description: >-
      This is the Algolia application you want to index your data to.
      You can find your credentials including application ID on your Algolia dashboard,
      under the [API keys tab](https://www.algolia.com/api-keys).
    type: string
    required: true

  - param: ALGOLIA_API_KEY
    label: Algolia API Key
    description: >-
      We recommend [creating a new API key](https://www.algolia.com/doc/guides/security/api-keys/#creating-and-managing-api-keys)
      with "addObject", "deleteObject", "listIndexes", "deleteIndex", "editSettings", and "settings" permissions.
      **Do not use the Admin API key**.
    type: secret
    required: true

  - param: ALT_OBJECT_ID
    label: Alternative Object Id
    description: >-
      Specify an alternative Firestore document property to use for the Algolia record Id.  Use `(path)` if the document path is desired as the Algolia ObjectID.  The default is the Firestore document Id.
      **If you set this property, make sure to clear out the Algolia Index since the ObjectID will be different resulting in duplicate records.**
    type: string
    required: false

  - param: TRANSFORM_FUNCTION
    label: Transform Function Name (Experimental)
    description: >-
      Specify a Firebase Cloud Function for any data transformation before saving into Algolia.
      Refer to [Call functions for your app](https://firebase.google.com/docs/functions/callable).
    type: string
    required: false

  - param: DO_FULL_INDEXING
    label: Full Index existing documents?
    description: >
      Should existing documents in the Firestore collection be indexed as well?
    type: select
    required: true
    options:
      - label: Yes
        value: true
      - label: No
        value: false

  - param: LOCATION
    label: Cloud Functions location
    description: >-
      Where do you want to deploy the functions created for this extension?
      You usually want a location close to your database.
      For help selecting a location, refer to the
      [location selection guide](https://firebase.google.com/docs/functions/locations).
    type: select
    options:
      - label: Iowa (us-central1)
        value: us-central1
      - label: South Carolina (us-east1)
        value: us-east1
      - label: Northern Virginia (us-east4)
        value: us-east4
      - label: Los Angeles (us-west2)
        value: us-west2
      - label: Salt Lake City (us-west3)
        value: us-west3
      - label: Las Vegas (us-west4)
        value: us-west4
      - label: Warsaw (europe-central2)
        value: europe-central2
      - label: Belgium (europe-west1)
        value: europe-west1
      - label: London (europe-west2)
        value: europe-west2
      - label: Frankfurt (europe-west3)
        value: europe-west3
      - label: Zurich (europe-west6)
        value: europe-west6
      - label: Hong Kong (asia-east2)
        value: asia-east2
      - label: Tokyo (asia-northeast1)
        value: asia-northeast1
      - label: Osaka (asia-northeast2)
        value: asia-northeast2
      - label: Seoul (asia-northeast3)
        value: asia-northeast3
      - label: Mumbai (asia-south1)
        value: asia-south1
      - label: Jakarta (asia-southeast2)
        value: asia-southeast2
      - label: Montreal (northamerica-northeast1)
        value: northamerica-northeast1
      - label: Sao Paulo (southamerica-east1)
        value: southamerica-east1
      - label: Sydney (australia-southeast1)
        value: australia-southeast1
    required: true
    immutable: true

lifecycleEvents:
  onInstall:
    function: executeFullIndexOperation
    processingMessage: "Indexing existing documents in ${COLLECTION_PATH}"
  onUpdate:
    function: executeFullIndexOperation
    processingMessage: "Indexing existing documents in ${COLLECTION_PATH}"
  onConfigure:
    function: executeFullIndexOperation
    processingMessage: "Indexing existing documents in ${COLLECTION_PATH}"