Merge pull request #561 from nextcloud/fix/assignment-timezones

fix(assignments): Add timezone to assignments

Author: marcelklehr

appinfo/info.xml

@@ -62,7 +62,7 @@ Known providers:
 
 More details on how to set this up in the [admin docs](https://docs.nextcloud.com/server/latest/admin_manual/ai/index.html)
 ]]>	</description>
-	<version>3.5.0-dev.1</version>
+	<version>3.5.0-dev.2</version>
 	<licence>agpl</licence>
 	<author>Julien Veyssier</author>
 	<namespace>Assistant</namespace>

lib/Controller/AssignmentsApiController.php

@@ -49,6 +49,7 @@ public function __construct(
 	 * @param string $prompt The prompt to be sent to the assistant when the assignment is executed
 	 * @param int $startsAt The timestamp when the assignment should start being executed
 	 * @param string $recurrence The recurrence rule for the assignment, in RRULE format (e.g. "FREQ=DAILY;INTERVAL=1" for a daily assignment)
+	 * @param string|null $timezone The timezone for this assignment (either the timezone name or a timezone offset, e.g. "Europe/Berlin" or "+0100" for UTC+1). Defaults to the user's current timezone
 	 * @return DataResponse<Http::STATUS_OK, array{assignment: AssistantAssignment}, array{}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_BAD_REQUEST, '', array{}>
 	 *
 	 * 200: User assignments returned
@@ -58,9 +59,9 @@ public function __construct(
 	#[NoAdminRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['assignments'])]
 	#[Http\Attribute\ApiRoute(verb: 'POST', url: '/assignments')]
-	public function createUserAssignment(string $title, string $prompt, int $startsAt, string $recurrence): DataResponse {
+	public function createUserAssignment(string $title, string $prompt, int $startsAt, string $recurrence, ?string $timezone): DataResponse {
 		try {
-			$assignment = $this->assignmentsService->createAssignment($this->userId, $title, $prompt, $startsAt, $recurrence);
+			$assignment = $this->assignmentsService->createAssignment($this->userId, $title, $prompt, $startsAt, $recurrence, $timezone);
 			$serializedAssignment = $assignment->jsonSerialize();
 			return new DataResponse(['assignment' => $serializedAssignment]);
 		} catch (InternalException $e) {
@@ -141,18 +142,19 @@ public function getUserAssignment(int $id): DataResponse {
 	 * @param string|null $prompt The prompt to be sent to the assistant when the assignment is executed
 	 * @param int|null $startsAt The timestamp when the assignment should start being executed
 	 * @param string|null $recurrence The recurrence rule for the assignment, in RRULE format
+	 * @param string|null $timezone The timezone for this assignment, omit to leave the current value in place. the value should be either the timezone name or a timezone offset, e.g. "Europe/Berlin" or "+0100" for UTC+1
 	 *
 	 * @return DataResponse<Http::STATUS_OK, array{assignment: AssistantAssignment}, array{}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, '', array{}>
 	 *
 	 * 200: User tasks returned
 	 * 403: User not logged in
-	 * 400: Malformed recurrence rule
+	 * 400: Malformed input
 	 * 404: Assignment not found
 	 */
 	#[NoAdminRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['assignments'])]
 	#[Http\Attribute\ApiRoute(verb: 'PATCH', url: '/assignments/{id}')]
-	public function updateUserAssignment(int $id, ?string $prompt, ?string $recurrence, ?int $startsAt): DataResponse {
+	public function updateUserAssignment(int $id, ?string $prompt, ?string $recurrence, ?int $startsAt, ?string $timezone): DataResponse {
 		if ($this->userId !== null) {
 			try {
 				$assignment = $this->assignmentMapper->find($this->userId, $id);
@@ -169,6 +171,13 @@ public function updateUserAssignment(int $id, ?string $prompt, ?string $recurren
 				if ($startsAt !== null) {
 					$assignment->setStartsAt($startsAt);
 				}
+				if ($timezone !== null) {
+					try {
+						$assignment->setTimezone($timezone);
+					} catch (\InvalidArgumentException $e) {
+						return new DataResponse('', Http::STATUS_BAD_REQUEST);
+					}
+				}
 				$assignment->setUpdatedAt($this->timeFactory->now()->getTimestamp());
 				$this->assignmentMapper->update($assignment);
 				/** @var AssistantAssignment $serializedAssignment */

lib/Db/Assignment.php

@@ -33,6 +33,7 @@
  * @method \void setUpdatedAt(int $updatedAt)
  * @method \void setLastRunAt(int $lastRunAt)
  * @method \int getLastRunAt()
+ * @method \string getTimezone()
  */
 class Assignment extends Entity implements \JsonSerializable {
 	/** @var string */
@@ -50,6 +51,9 @@ class Assignment extends Entity implements \JsonSerializable {
 	/** @var int */
 	protected $lastRunAt;
 
+	/** @var string */
+	protected $timezone;
+
 	public static $columns = [
 		'id',
 		'user_id',
@@ -59,6 +63,7 @@ class Assignment extends Entity implements \JsonSerializable {
 		'created_at',
 		'updated_at',
 		'last_run_at',
+		'timezone'
 	];
 	public static $fields = [
 		'id',
@@ -69,6 +74,7 @@ class Assignment extends Entity implements \JsonSerializable {
 		'createdAt',
 		'updatedAt',
 		'lastRunAt',
+		'timezone'
 	];
 
 	public function __construct() {
@@ -79,6 +85,7 @@ public function __construct() {
 		$this->addType('createdAt', Types::BIGINT);
 		$this->addType('updatedAt', Types::BIGINT);
 		$this->addType('lastRunAt', Types::BIGINT);
+		$this->addType('timezone', Types::STRING);
 	}
 
 	#[\ReturnTypeWillChange]
@@ -92,6 +99,7 @@ public function jsonSerialize() {
 			'created_at' => $this->getCreatedAt(),
 			'updated_at' => $this->getUpdatedAt(),
 			'last_run_at' => $this->getLastRunAt(),
+			'timezone' => $this->getTimezone(),
 		];
 	}
 
@@ -107,6 +115,18 @@ public function setRecurrence(string $recurrence): void {
 		$this->setter('recurrence', [$recurrence]);
 	}
 
+	/**
+	 * @throws \InvalidArgumentException
+	 */
+	public function setTimezone(string $timezone): void {
+		try {
+			$tz = new \DateTimeZone($timezone);
+		} catch (\Throwable $e) {
+			throw new \InvalidArgumentException('Invalid timezone: ' . $timezone, previous: $e);
+		}
+		$this->setter('timezone', [$tz->getName()]);
+	}
+
 	/**
 	 * Evaluates the recurrence rule and checks if a run is due
 	 */
@@ -115,9 +135,9 @@ public function isDueToRun(\DateTimeImmutable $now): bool {
 			$startsAt = new \DateTime('@' . $this->getStartsAt());
 			$lastRunAt = new \DateTime('@' . $this->getLastRunAt());
 			// Find recurrences after the last run or after the current time if this assignment has never run
-			$rule = new Rule($this->getRecurrence(), $startsAt);
+			$rule = new Rule($this->getRecurrence(), $startsAt, timezone: $this->getTimezone());
 			$transformer = new \Recurr\Transformer\ArrayTransformer();
-			$constraint = new AfterConstraint($this->getLastRunAt() !== 0 ? $lastRunAt : $startsAt, false);
+			$constraint = $this->getLastRunAt() !== 0 ? new AfterConstraint($lastRunAt, false) : new AfterConstraint($startsAt, true);
 			/** @var RecurrenceCollection $collection */
 			$collection = $transformer->transform($rule, $constraint);
 			if ($collection->isEmpty()) {

lib/Migration/Version030500Date20260528083738.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Assistant\Migration;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+class Version030500Date20260528083738 extends SimpleMigrationStep {
+
+	/**
+	 * @param IOutput $output
+	 * @param Closure(): ISchemaWrapper $schemaClosure
+	 * @param array $options
+	 * @return null|ISchemaWrapper
+	 */
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+		$schemaChanged = false;
+
+		if ($schema->hasTable('assistant_assignments')) {
+			$table = $schema->getTable('assistant_assignments');
+			if (!$table->hasColumn('timezone')) {
+				$table->addColumn('timezone', Types::STRING, [
+					'notnull' => true,
+					'length' => 256,
+					'default' => 'UTC',
+				]);
+				$schemaChanged = true;
+			}
+		}
+
+		return $schemaChanged ? $schema : null;
+	}
+}

lib/ResponseDefinitions.php

@@ -94,7 +94,8 @@
  *      created_at: int,
  *      updated_at: int,
  *      starts_at: int,
- *      last_run_at: int
+ *      last_run_at: int,
+ *      timezone: string,
  *  }
  */
 class ResponseDefinitions {

lib/Service/AssignmentsService.php

@@ -19,6 +19,7 @@
 use OCP\AppFramework\Utility\ITimeFactory;
 use OCP\BackgroundJob\IJobList;
 use OCP\DB\Exception;
+use OCP\IDateTimeZone;
 use OCP\IL10N;
 use Psr\Log\LoggerInterface;
 
@@ -31,6 +32,7 @@ public function __construct(
 		private LoggerInterface $logger,
 		private IJobList $jobList,
 		private IL10N $l10n,
+		private IDateTimeZone $dateTimeZone,
 	) {
 	}
 
@@ -39,7 +41,7 @@ public function __construct(
 	 * @throws UnauthorizedException
 	 * @throws BadRequestException
 	 */
-	public function createAssignment(?string $userId, string $title, string $prompt, int $startsAt, string $recurrence): Assignment {
+	public function createAssignment(?string $userId, string $title, string $prompt, int $startsAt, string $recurrence, ?string $timezone): Assignment {
 		if ($userId === null) {
 			throw new UnauthorizedException();
 		}
@@ -56,6 +58,14 @@ public function createAssignment(?string $userId, string $title, string $prompt,
 		} catch (\InvalidArgumentException $e) {
 			throw new BadRequestException('Invalid recurrence rule', previous: $e);
 		}
+		if ($timezone === null) {
+			$timezone = $this->dateTimeZone->getTimeZone(userId: $userId);
+		}
+		try {
+			$assignment->setTimezone($timezone);
+		} catch (\InvalidArgumentException $e) {
+			throw new BadRequestException('Invalid recurrence rule', previous: $e);
+		}
 		try {
 			$this->assignmentMapper->insert($assignment);
 		} catch (Exception $e) {

openapi.json

@@ -30,7 +30,8 @@
                     "created_at",
                     "updated_at",
                     "starts_at",
-                    "last_run_at"
+                    "last_run_at",
+                    "timezone"
                 ],
                 "properties": {
                     "id": {
@@ -61,6 +62,9 @@
                     "last_run_at": {
                         "type": "integer",
                         "format": "int64"
+                    },
+                    "timezone": {
+                        "type": "string"
                     }
                 }
             },
@@ -5356,6 +5360,11 @@
                                     "recurrence": {
                                         "type": "string",
                                         "description": "The recurrence rule for the assignment, in RRULE format (e.g. \"FREQ=DAILY;INTERVAL=1\" for a daily assignment)"
+                                    },
+                                    "timezone": {
+                                        "type": "string",
+                                        "nullable": true,
+                                        "description": "The timezone for this assignment (either the timezone name or a timezone offset, e.g. \"Europe/Berlin\" or \"+0100\" for UTC+1). Defaults to the user's current timezone"
                                     }
                                 }
                             }
@@ -5925,6 +5934,11 @@
                                         "format": "int64",
                                         "nullable": true,
                                         "description": "The timestamp when the assignment should start being executed"
+                                    },
+                                    "timezone": {
+                                        "type": "string",
+                                        "nullable": true,
+                                        "description": "The timezone for this assignment, omit to leave the current value in place. the value should be either the timezone name or a timezone offset, e.g. \"Europe/Berlin\" or \"+0100\" for UTC+1"
                                     }
                                 }
                             }
@@ -6023,7 +6037,7 @@
                         }
                     },
                     "400": {
-                        "description": "Malformed recurrence rule",
+                        "description": "Malformed input",
                         "content": {
                             "application/json": {
                                 "schema": {

tests/unit/Db/AssignmentTest.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Assistant\Tests;
+
+use OCA\Assistant\Db\Assignment;
+
+class AssignmentTest extends \PHPUnit\Framework\TestCase {
+
+	/**
+	 * @dataProvider isDueDataProvider
+	 */
+	public function testIsDue(string $rrule, string $startsAt, string $lastRunAt, string $timezone, string $now, bool $expected) {
+		$assignment = new Assignment();
+		$assignment->setRecurrence($rrule);
+		$assignment->setStartsAt((new \DateTimeImmutable($startsAt))->getTimestamp());
+		$assignment->setLastRunAt((new \DateTimeImmutable($lastRunAt))->getTimestamp());
+		$assignment->setTimezone($timezone);
+		self::assertEquals($expected, $assignment->isDueToRun(new \DateTimeImmutable($now)));
+	}
+
+	public function isDueDataProvider(): array {
+		return [
+			['FREQ=DAILY', '1970-01-02T00:00:00Z', '@0', 'UTC', '1970-01-02T00:00:00Z', true],
+			['FREQ=DAILY', '@0', '@0', 'UTC', '1970-01-02T00:00:00Z', false],
+			['FREQ=DAILY;BYHOUR=8', '@0', '@0', 'UTC', '1970-01-01T08:00:00Z', true],
+			['FREQ=DAILY;BYHOUR=8', '@0', '1970-01-01T08:00:00Z', 'UTC', '1970-01-01T08:00:01Z', false],
+			['FREQ=DAILY;BYHOUR=8', '@0', '@0', '+0200', '1970-01-01T10:00:00Z', true],
+			['FREQ=DAILY;BYHOUR=8', '@0', '1970-01-01T10:00:00Z', '+0200', '1970-01-01T10:00:00Z', false],
+			['FREQ=DAILY;BYHOUR=8', '@0', '1970-01-01T10:00:00Z', '+0200', '1970-01-02T10:00:00Z', true],
+			['FREQ=DAILY;BYHOUR=8', '@0', '1970-01-01T10:00:00Z', '+0200', '1970-01-02T10:00:00Z', true],
+			['FREQ=DAILY;BYHOUR=8', '@0', '1970-01-01T10:00:00Z', '+0200', '2027-01-02T10:00:00Z', true],
+		];
+	}
+}