Cloud Functions

The functions module integrates Firebase Cloud Functions in your project. It provides a serverless framework to run backend code in response to events triggered by HTTPS requests, background events, or scheduled jobs.

• Directoryfunctions/src/

  • Directoryaccount/ // Account management

    • …
  • Directorypayment/ // Payment processing

    • …
  • Directorychat/ // Chat functionality

    • …
  • Directorygenkit/ // AI features (optional)

    • …
  • index.ts // Function exports
  • main.ts // Express app setup
  • store.ts // Firestore helpers

Setup

From within the functions folder:

1. Install dependencies:

   npm install

2. Create a .env file in the functions folder:

   # Required for Lemon Squeezy payment module
   KEY_LEMON_SQUEEZY_API=xxx

3. Modify and adapt for your needs

4. Deploy the functions:

   firebase deploy --only functions

Express Engine

ShipFlutter uses Express.js to handle HTTP functions. The setup is defined in main.ts and it means all HTTP endpoints:

1. Are prefixed with /v1 for versioning
2. Accept JSON payloads automatically
3. Follow the pattern: https://REGION-PROJECT_ID.cloudfunctions.net/api/v1/PATH

import express from "express";
import bodyParser from "body-parser";

const app = express();
const main = express();

// All routes are prefixed with /v1
main.use("/v1", app);
main.use(bodyParser.json());

// Example CRUD endpoint
// URL: https://REGION-PROJECT_ID.cloudfunctions.net/api/v1/hello
app.post("/hello", (req, res) => {
  // Handle webhook
  res.status(200).send("OK");
});

Tip

The Express engine makes it easy to add new endpoints. Just use app.get(), app.post(), etc. in the respective module’s file.

Function Types

ShipFlutter uses several types of Cloud Functions:

HTTP Functions

// Express API endpoint
app.post("/payment/create", async (req, res) => {
  // Handle webhook
  res.status(200).send("OK");
});

Used for webhooks and external integrations. For example:

https://REGION-PROJECT.cloudfunctions.net/api/v1/payment/event/ls

Callable Functions

// Secure callable function
exports.hello = onCall(async (request) => {
  const name = request.auth?.token?.name;
  return `Hello ${name}`;
});

Called from the app using the Firebase SDK:

final result = await functionsService.instance.call(
  'hello',
  parser: (data) => data as String,
);

Firestore Triggers

// React to document changes
exports.onItemUpdate = onDocumentUpdated(
  "items/{id}",
  async (event) => {
    // Get before and after data
    const before = event.data.before.data();
    const after = event.data.after.data();

    // Skip if no changes
    if (before.status === after.status) {
      return null;
    }

    // Update related data
    return event.data.after.ref.set({
      lastUpdate: new Date(),
    }, { merge: true });
  }
);

Tip

Use Firestore triggers to maintain data consistency and create reactive workflows.

Auth Triggers

// React to user creation
exports.onUserCreated = onUserCreated(async (event) => {
  const user = event.data;

  // Create user profile
  await db.collection('users').doc(user.uid).set({
    email: user.email,
    createdAt: new Date(),
    // Add default data
  });
});

Tip

Auth triggers are perfect for user onboarding flows and maintaining user data.

Testing Functions

Test your functions locally using the Firebase Emulator:

cd functions
npm run serve

Tip

The emulator will watch for changes and automatically rebuild your functions. You can modify which emulators to start in package.json under the serve script.

Available Modules

ShipFlutter includes several function modules:

1. Account Management (/account)

   • User data synchronization
   • Account deletion
   • Social auth

2. Payment Processing (/payment)

   • RevenueCat webhooks
   • LemonSqueezy webhooks
   • Product syncing

3. Chat Features (/chat)

   • Message handling
   • Chat history
   • Real-time updates

4. GenKit (/genkit)

   • AI-powered features
   • Vertex AI and Gemini integration
   • Custom flows

Using Functions in Flutter

The AppFunctions class provides a type-safe way to call Cloud Functions:

// Call a function with custom payload
final result = await functionsService.instance.call(
  'functionName',
  payload: {'key': 'value'},
  parser: (data) => MyModel.fromJson(data),
);

// Simple function call
final greeting = await functionsService.instance.call<String>(
  'hello',
  parser: (data) => data as String,
);

Caution

Always handle FirebaseFunctionsException when calling functions to manage errors gracefully.