feat: add scheduler hook support (#11)

Author: Lyokone

example/basic/lib/main.dart

@@ -417,6 +417,41 @@ void main(List<String> args) {
       },
     );
 
+    // ==========================================================================
+    // Scheduler trigger examples
+    // ==========================================================================
+
+    // Basic scheduled function - runs every day at midnight
+    firebase.scheduler.onSchedule(
+      schedule: '0 0 * * *',
+      (event) async {
+        print('Scheduled function triggered:');
+        print('  Job Name: ${event.jobName}');
+        print('  Schedule Time: ${event.scheduleTime}');
+        // Perform daily cleanup, send reports, etc.
+      },
+    );
+
+    // Scheduled function with timezone and retry config
+    firebase.scheduler.onSchedule(
+      schedule: '0 9 * * 1-5',
+      options: const ScheduleOptions(
+        timeZone: TimeZone('America/New_York'),
+        retryConfig: RetryConfig(
+          retryCount: RetryCount(3),
+          maxRetrySeconds: MaxRetrySeconds(60),
+          minBackoffSeconds: MinBackoffSeconds(5),
+          maxBackoffSeconds: MaxBackoffSeconds(30),
+        ),
+        memory: Memory(MemoryOption.mb256),
+      ),
+      (event) async {
+        print('Weekday morning report:');
+        print('  Executed at: ${event.scheduleDateTime}');
+        // Generate and send morning reports
+      },
+    );
+
     print('Functions registered successfully!');
   });
 }

lib/builder.dart

@@ -38,6 +38,8 @@ class _TypeCheckers {
       TypeChecker.fromRuntime(ff.PerformanceNamespace);
   static final identityNamespace =
       TypeChecker.fromRuntime(ff.IdentityNamespace);
+  static final schedulerNamespace =
+      TypeChecker.fromRuntime(ff.SchedulerNamespace);
 }
 
 /// The main builder that generates functions.yaml.
@@ -186,6 +188,13 @@ class _FirebaseFunctionsVisitor extends RecursiveAstVisitor<void> {
       _extractIdentityFunction(node, methodName);
     }
 
+    // Check for Scheduler function declarations
+    if (target != null && _isSchedulerNamespace(target)) {
+      if (methodName == 'onSchedule') {
+        _extractSchedulerFunction(node);
+      }
+    }
+
     // Check for parameter definitions (top-level function calls with no target)
     if (target == null && _isParamDefinition(methodName)) {
       _extractParameterFromMethod(node, methodName);
@@ -339,6 +348,13 @@ class _FirebaseFunctionsVisitor extends RecursiveAstVisitor<void> {
     return _TypeCheckers.identityNamespace.isExactlyType(staticType);
   }
 
+  /// Checks if the target is firebase.scheduler.
+  bool _isSchedulerNamespace(Expression target) {
+    final staticType = target.staticType;
+    if (staticType == null) return false;
+    return _TypeCheckers.schedulerNamespace.isExactlyType(staticType);
+  }
+
   /// Checks if this is a parameter definition function.
   bool _isParamDefinition(String name) =>
       name == 'defineString' ||
@@ -639,6 +655,101 @@ class _FirebaseFunctionsVisitor extends RecursiveAstVisitor<void> {
     );
   }
 
+  /// Extracts a Scheduler function declaration.
+  void _extractSchedulerFunction(MethodInvocation node) {
+    // Extract schedule from named argument
+    final scheduleArg = _findNamedArg(node, 'schedule');
+    if (scheduleArg == null) return;
+
+    final schedule = _extractStringLiteral(scheduleArg);
+    if (schedule == null) return;
+
+    // Generate function name from schedule (matching runtime behavior)
+    final sanitized = schedule
+        .replaceAll(' ', '_')
+        .replaceAll('*', '')
+        .replaceAll('/', '')
+        .replaceAll('-', '')
+        .replaceAll(',', '');
+    final functionName = 'onSchedule_$sanitized';
+
+    // Extract options if present
+    final optionsArg = _findNamedArg(node, 'options');
+    String? timeZone;
+    Map<String, dynamic>? retryConfig;
+
+    if (optionsArg is InstanceCreationExpression) {
+      timeZone = _extractSchedulerTimeZone(optionsArg);
+      retryConfig = _extractRetryConfig(optionsArg);
+    }
+
+    endpoints[functionName] = _EndpointSpec(
+      name: functionName,
+      type: 'scheduler',
+      schedule: schedule,
+      timeZone: timeZone,
+      retryConfig: retryConfig,
+      options: optionsArg is InstanceCreationExpression ? optionsArg : null,
+      variableToParamName: _variableToParamName,
+    );
+  }
+
+  /// Extracts timeZone from ScheduleOptions.
+  String? _extractSchedulerTimeZone(InstanceCreationExpression node) {
+    final timeZoneArg = node.argumentList.arguments
+        .whereType<NamedExpression>()
+        .where((e) => e.name.label.name == 'timeZone')
+        .map((e) => e.expression)
+        .firstOrNull;
+
+    if (timeZoneArg is InstanceCreationExpression) {
+      // TimeZone('America/New_York')
+      final args = timeZoneArg.argumentList.arguments;
+      if (args.isNotEmpty && args.first is StringLiteral) {
+        return (args.first as StringLiteral).stringValue;
+      }
+    }
+    return null;
+  }
+
+  /// Extracts RetryConfig from ScheduleOptions.
+  Map<String, dynamic>? _extractRetryConfig(InstanceCreationExpression node) {
+    final retryConfigArg = node.argumentList.arguments
+        .whereType<NamedExpression>()
+        .where((e) => e.name.label.name == 'retryConfig')
+        .map((e) => e.expression)
+        .firstOrNull;
+
+    if (retryConfigArg is! InstanceCreationExpression) return null;
+
+    final config = <String, dynamic>{};
+
+    for (final arg in retryConfigArg.argumentList.arguments) {
+      if (arg is! NamedExpression) continue;
+
+      final fieldName = arg.name.label.name;
+      final value = _extractRetryConfigValue(arg.expression);
+      if (value != null) {
+        config[fieldName] = value;
+      }
+    }
+
+    return config.isEmpty ? null : config;
+  }
+
+  /// Extracts a value from a retry config option.
+  dynamic _extractRetryConfigValue(Expression expression) {
+    if (expression is InstanceCreationExpression) {
+      final args = expression.argumentList.arguments;
+      if (args.isNotEmpty) {
+        final first = args.first;
+        if (first is IntegerLiteral) return first.value;
+        if (first is DoubleLiteral) return first.value;
+      }
+    }
+    return null;
+  }
+
   /// Extracts a boolean field from an InstanceCreationExpression.
   bool? _extractBoolField(InstanceCreationExpression node, String fieldName) {
     final arg = node.argumentList.arguments
@@ -888,11 +999,14 @@ class _EndpointSpec {
     this.idToken,
     this.accessToken,
     this.refreshToken,
+    this.schedule,
+    this.timeZone,
+    this.retryConfig,
     this.options,
     this.variableToParamName = const {},
   });
   final String name;
-  // 'https', 'callable', 'pubsub', 'firestore', 'database', 'alert', 'blocking'
+  // 'https', 'callable', 'pubsub', 'firestore', 'database', 'alert', 'blocking', 'scheduler'
   final String type;
   final String? topic; // For Pub/Sub functions
   final String? firestoreEventType; // For Firestore: onDocumentCreated, etc.
@@ -908,6 +1022,9 @@ class _EndpointSpec {
   final bool? idToken; // For Identity: pass ID token
   final bool? accessToken; // For Identity: pass access token
   final bool? refreshToken; // For Identity: pass refresh token
+  final String? schedule; // For Scheduler: cron expression
+  final String? timeZone; // For Scheduler: timezone
+  final Map<String, dynamic>? retryConfig; // For Scheduler: retry configuration
   final InstanceCreationExpression? options;
   final Map<String, String> variableToParamName;
 
@@ -1458,6 +1575,13 @@ String _generateYaml(
     buffer.writeln('  - api: "identitytoolkit.googleapis.com"');
     buffer.writeln('    reason: "Needed for auth blocking functions"');
   }
+  // Add cloudscheduler API if there are scheduler functions
+  final hasSchedulerFunctions =
+      endpoints.values.any((e) => e.type == 'scheduler');
+  if (hasSchedulerFunctions) {
+    buffer.writeln('  - api: "cloudscheduler.googleapis.com"');
+    buffer.writeln('    reason: "Needed for scheduled functions"');
+  }
   buffer.writeln();
 
   // Generate endpoints section
@@ -1685,6 +1809,37 @@ String _generateYaml(
         } else {
           buffer.writeln('      options: {}');
         }
+      } else if (endpoint.type == 'scheduler' && endpoint.schedule != null) {
+        buffer.writeln('    scheduleTrigger:');
+        buffer.writeln('      schedule: "${endpoint.schedule}"');
+        if (endpoint.timeZone != null) {
+          buffer.writeln('      timeZone: "${endpoint.timeZone}"');
+        }
+        if (endpoint.retryConfig != null && endpoint.retryConfig!.isNotEmpty) {
+          buffer.writeln('      retryConfig:');
+          final config = endpoint.retryConfig!;
+          if (config.containsKey('retryCount')) {
+            buffer.writeln('        retryCount: ${config['retryCount']}');
+          }
+          if (config.containsKey('maxRetrySeconds')) {
+            buffer.writeln(
+              '        maxRetrySeconds: ${config['maxRetrySeconds']}',
+            );
+          }
+          if (config.containsKey('minBackoffSeconds')) {
+            buffer.writeln(
+              '        minBackoffSeconds: ${config['minBackoffSeconds']}',
+            );
+          }
+          if (config.containsKey('maxBackoffSeconds')) {
+            buffer.writeln(
+              '        maxBackoffSeconds: ${config['maxBackoffSeconds']}',
+            );
+          }
+          if (config.containsKey('maxDoublings')) {
+            buffer.writeln('        maxDoublings: ${config['maxDoublings']}');
+          }
+        }
       }
     }
   }

lib/firebase_functions.dart

@@ -81,5 +81,7 @@ export 'src/https/https.dart';
 export 'src/identity/identity.dart';
 // Pub/Sub triggers
 export 'src/pubsub/pubsub.dart';
+// Scheduler triggers
+export 'src/scheduler/scheduler.dart';
 // Core runtime
 export 'src/server.dart' show fireUp;

lib/src/firebase.dart

@@ -11,6 +11,7 @@ import 'firestore/firestore_namespace.dart';
 import 'https/https_namespace.dart';
 import 'identity/identity_namespace.dart';
 import 'pubsub/pubsub_namespace.dart';
+import 'scheduler/scheduler_namespace.dart';
 
 /// Main Firebase Functions instance.
 ///
@@ -85,6 +86,9 @@ class Firebase {
 
   /// Identity Platform namespace.
   IdentityNamespace get identity => IdentityNamespace(this);
+
+  /// Scheduler namespace.
+  SchedulerNamespace get scheduler => SchedulerNamespace(this);
 }
 
 /// Extension for internal function registration.

lib/src/scheduler/options.dart

@@ -0,0 +1,100 @@
+import '../common/options.dart';
+
+/// Options for scheduled functions.
+///
+/// Extends [GlobalOptions] with scheduler-specific configuration.
+class ScheduleOptions extends GlobalOptions {
+  /// Creates schedule options.
+  const ScheduleOptions({
+    this.timeZone,
+    this.retryConfig,
+    super.concurrency,
+    super.cpu,
+    super.ingressSettings,
+    super.invoker,
+    super.labels,
+    super.minInstances,
+    super.maxInstances,
+    super.memory,
+    super.omit,
+    super.preserveExternalChanges,
+    super.region,
+    super.secrets,
+    super.serviceAccount,
+    super.timeoutSeconds,
+    super.vpcConnector,
+    super.vpcConnectorEgressSettings,
+  });
+
+  /// The timezone that the schedule executes in.
+  ///
+  /// If not specified, defaults to UTC.
+  ///
+  /// Example: `'America/New_York'`, `'Europe/London'`
+  final TimeZone? timeZone;
+
+  /// Retry configuration for failed function executions.
+  final RetryConfig? retryConfig;
+}
+
+/// Retry configuration for scheduled functions.
+///
+/// Configures how Cloud Scheduler retries failed invocations.
+class RetryConfig {
+  /// Creates a retry configuration.
+  const RetryConfig({
+    this.retryCount,
+    this.maxRetrySeconds,
+    this.minBackoffSeconds,
+    this.maxBackoffSeconds,
+    this.maxDoublings,
+  });
+
+  /// The number of retry attempts for a failed run.
+  ///
+  /// If set to 0, the job will not be retried on failure.
+  final RetryCount? retryCount;
+
+  /// The time limit for retrying a failed job, in seconds.
+  ///
+  /// After this time, no more retries will be attempted.
+  final MaxRetrySeconds? maxRetrySeconds;
+
+  /// The minimum time to wait before retrying, in seconds.
+  ///
+  /// Must be between 0 and 3600.
+  final MinBackoffSeconds? minBackoffSeconds;
+
+  /// The maximum time to wait before retrying, in seconds.
+  ///
+  /// Must be between 0 and 3600.
+  final MaxBackoffSeconds? maxBackoffSeconds;
+
+  /// The maximum number of times that the backoff interval
+  /// will be doubled before the interval starts increasing linearly.
+  ///
+  /// After this many doublings, subsequent retries will increase
+  /// the interval linearly according to the formula:
+  /// `delay = maxBackoffSeconds + (attempt - maxDoublings) * maxBackoffSeconds`
+  final MaxDoublings? maxDoublings;
+}
+
+// Type aliases for scheduler-specific options
+
+/// The timezone option type.
+typedef TimeZone = Option<String>;
+
+/// The retry count option type.
+typedef RetryCount = DeployOption<int>;
+
+/// The max retry seconds option type.
+typedef MaxRetrySeconds = DeployOption<int>;
+
+/// The min backoff seconds option type.
+typedef MinBackoffSeconds = DeployOption<int>;
+
+/// The max backoff seconds option type.
+typedef MaxBackoffSeconds = DeployOption<int>;
+
+/// The max doublings option type.
+typedef MaxDoublings = DeployOption<int>;