feat(ocs): add OCS extractor and workflow

.github/workflows/openapi.yml

@@ -0,0 +1,83 @@
+# This workflow is provided via the organization template repository
+#
+# https://github.com/nextcloud/.github
+# https://docs.github.com/en/actions/learn-github-actions/sharing-workflows-with-your-organization
+#
+# SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+# SPDX-FileCopyrightText: 2024 Arthur Schiwon <blizzz@arthur-schiwon.de>
+# SPDX-License-Identifier: MIT
+
+name: OpenAPI
+
+on: pull_request
+
+permissions:
+  contents: read
+
+concurrency:
+  group: openapi-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  openapi:
+    runs-on: ubuntu-latest
+
+    if: ${{ github.repository_owner != 'nextcloud-gmbh' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+
+      - name: Get php version
+        id: php_versions
+        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
+
+      - name: Set up php
+        uses: shivammathur/setup-php@2e947f1f6932d141d076ca441d0e1e881775e95b # v2.31.0
+        with:
+          php-version: ${{ steps.php_versions.outputs.php-available }}
+          extensions: xml
+          coverage: none
+          ini-file: development
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check Typescript OpenApi types
+        id: check_typescript_openapi
+        uses: andstor/file-existence-action@076e0072799f4942c8bc574a82233e1e4d13e9d6 # v3.0.0
+        with:
+          files: "src/types/openapi/openapi*.ts"
+
+      - name: Read package.json node and npm engines version
+        if: steps.check_typescript_openapi.outputs.files_exists == 'true'
+        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
+        id: node_versions
+        # Continue if no package.json
+        continue-on-error: true
+        with:
+          fallbackNode: '^20'
+          fallbackNpm: '^10'
+
+      - name: Set up node ${{ steps.node_versions.outputs.nodeVersion }}
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        with:
+          node-version: ${{ steps.node_versions.outputs.nodeVersion }}
+
+      - name: Set up npm ${{ steps.node_versions.outputs.npmVersion }}
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        run: npm i -g 'npm@${{ steps.node_versions.outputs.npmVersion }}'
+
+      - name: Install dependencies & build
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        env:
+          CYPRESS_INSTALL_BINARY: 0
+          PUPPETEER_SKIP_DOWNLOAD: true
+        run: |
+          npm ci
+
+      - name: Set up dependencies
+        run: composer i
+
+      - name: Regenerate OpenAPI
+        run: composer run openapi

REUSE.toml

@@ -78,7 +78,7 @@ SPDX-FileCopyrightText = "2021 Nextcloud GmbH and Nextcloud contributors"
 SPDX-License-Identifier = "AGPL-3.0-or-later"
 
 [[annotations]]
-path = ["vendor-bin/cs-fixer/composer.json", "vendor-bin/cs-fixer/composer.lock", "vendor-bin/mozart/composer.json", "vendor-bin/mozart/composer.lock", "vendor-bin/phpunit/composer.json", "vendor-bin/phpunit/composer.lock", "vendor-bin/rector/composer.json", "vendor-bin/rector/composer.lock"]
+path = ["vendor-bin/cs-fixer/composer.json", "vendor-bin/cs-fixer/composer.lock", "vendor-bin/mozart/composer.json", "vendor-bin/mozart/composer.lock", "vendor-bin/openapi/composer.*", "vendor-bin/phpunit/composer.json", "vendor-bin/phpunit/composer.lock", "vendor-bin/rector/composer.json", "vendor-bin/rector/composer.lock"]
 precedence = "aggregate"
 SPDX-FileCopyrightText = "2021-2024 Nextcloud GmbH and Nextcloud contributors"
 SPDX-License-Identifier = "AGPL-3.0-or-later"

composer.json

@@ -75,7 +75,8 @@
 		"test:integration": "phpunit -c tests/phpunit.integration.xml --fail-on-warning",
 		"test:integration:dev": "phpunit -c tests/phpunit.integration.xml --no-coverage --order-by=defects --stop-on-defect --fail-on-warning --stop-on-error --stop-on-failure",
 		"test:unit": "phpunit -c tests/phpunit.unit.xml --fail-on-warning",
-		"test:unit:dev": "phpunit -c tests/phpunit.unit.xml --no-coverage --order-by=defects --stop-on-defect --fail-on-warning --stop-on-error --stop-on-failure"
+		"test:unit:dev": "phpunit -c tests/phpunit.unit.xml --no-coverage --order-by=defects --stop-on-defect --fail-on-warning --stop-on-error --stop-on-failure",
+		"openapi": "generate-spec"
 	},
 	"extra": {
 		"mozart": {

krankerl.toml

@@ -5,4 +5,5 @@ before_cmds = [
 	"composer install --no-dev -o",
 	"npm install --deps",
 	"npm run build",
+	"composer openapi"
 ]

lib/Controller/MessageApiController.php

@@ -43,8 +43,8 @@
 use function array_merge;
 
 /**
- * @psalm-import-type MessageApiResponse from ResponseDefinitions
- * @psalm-import-type MessageApiAttachment from ResponseDefinitions
+ * @psalm-import-type MailMessageApiResponse from ResponseDefinitions
+ * @psalm-import-type MailMessageApiAttachment from ResponseDefinitions
  */
 class MessageApiController extends OCSController {
 
@@ -72,15 +72,17 @@ public function __construct(
 	}
 
 	/**
+	 * Send an email though a mail account that has been configured with Nextcloud Mail
+	 *
 	 * @param int $accountId  The mail account to use for SMTP
 	 * @param string $fromEmail  The "From" email address or alias email address
 	 * @param string $subject  The subject
 	 * @param string $body  The message body
 	 * @param bool $isHtml  If the message body contains HTML
-	 * @param array $to  An array of "To" recipients in the format ['label' => 'Name', 'email' => 'Email Address'] or ['email' => 'Email Address']
-	 * @param array $cc  An optional array of 'CC' recipients in the format ['label' => 'Name', 'email' => 'Email Address'] or ['email' => 'Email Address']
-	 * @param array $bcc  An optional array of 'BCC' recipients in the format ['label' => 'Name', 'email' => 'Email Address'] or ['email' => 'Email Address']
-	 * @param ?string $references  An optional string of an RFC2392 <message-id> to set the "Reply-To" and "References" header on sending
+	 * @param list<array{ label?: string, email: string}> $to  An array of "To" recipients in the format ['label' => 'Name', 'email' => 'Email Address'] or ['email' => 'Email Address']
+	 * @param array<empty>|list<array{ label?: string, email: string}> $cc  An optional array of 'CC' recipients in the format ['label' => 'Name', 'email' => 'Email Address'] or ['email' => 'Email Address']
+	 * @param array<empty>|list<array{ label?: string, email: string}> $bcc  An optional array of 'BCC' recipients in the format ['label' => 'Name', 'email' => 'Email Address'] or ['email' => 'Email Address']
+	 * @param ?string $references  An optional string of an RFC2392 "message-id" to set the "Reply-To" and "References" header on sending
 	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_ACCEPTED|Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, string, array{}>
 	 *
 	 * 200: The email was sent
@@ -207,8 +209,10 @@ public function send(
 	}
 
 	/**
-	 * @param int $id
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_PARTIAL_CONTENT, MessageApiResponse, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, string, array{}>
+	 * Get a mail message with its metadata
+	 *
+	 * @param int $id  the message id
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_PARTIAL_CONTENT, MailMessageApiResponse, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, string, array{}>
 	 *
 	 * 200: Message found
 	 * 206: Message could not be decrypted, no "body" data returned
@@ -296,8 +300,10 @@ public function get(int $id): DataResponse {
 	}
 
 	/**
+	 * Get the raw rfc2822 email
+	 *
 	 * @param int $id the id of the message
-	 * @return DataResponse<Http::STATUS_OK|?string, array{}>|DataResponse<Http::STATUS_NOT_FOUND, string, array{}>
+	 * @return DataResponse<Http::STATUS_OK, ?string, array{}>|DataResponse<Http::STATUS_NOT_FOUND, string, array{}>
 	 *
 	 * 200: Message found
 	 * 404: User was not logged in
@@ -356,9 +362,11 @@ private function enrichDownloadUrl(int $id, array $attachment): array {
 	}
 
 	/**
-	 * @param int $id
-	 * @param string $attachmentId
-	 * @return DataResponse<Http::STATUS_OK, MessageApiAttachment, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, string, array{}>
+	 * Get a mail message's attachments
+	 *
+	 * @param int $id  the mail id
+	 * @param string $attachmentId  the attachment id
+	 * @return DataResponse<Http::STATUS_OK, MailMessageApiAttachment, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, string, array{}>
 	 *
 	 * 200: Message found
 	 * 404: User was not logged in

lib/ResponseDefinitions.php

@@ -15,35 +15,35 @@
  *     messageId: string,
  *     from: list<array{label: string, email: string}>,
  *     to: list<array{label: string, email: string}>,
- *     replyTo: array<empty>|list<array{label: string, email: string}>,
- *     cc: array<empty>|list<array{label: string, email: string}>,
- *     bcc: array<empty>|list<array{label: string, email: string}>,
+ *     replyTo: list<array{label: string, email: string}>,
+ *     cc: list<array{label: string, email: string}>,
+ *     bcc: list<array{label: string, email: string}>,
  *     subject: string,
  *     dateInt: int<0, max>,
  *     flags: array{seen: bool, flagged: bool, answered: bool, deleted: bool, draft: bool, forwarded: bool, hasAttachments: bool, mdnsent: bool, important: bool},
  *     hasHtmlBody?: bool,
  *     body?: string,
  *     dispositionNotificationTo: string,
  *     hasDkimSignature: bool,
- *     phishingDetails: array{checks: list<array{type: string, isPhishing: bool, message: string, additionalData: array}>, warning: bool},
+ *     phishingDetails: array{checks: list<array{type: string, isPhishing: bool, message: string, additionalData: array<string, mixed>}>, warning: bool},
  *     unsubscribeUrl: ?string,
  *     isOneClickUnsubscribe: bool,
  *     unsubscribeMailTo: ?string,
- *     scheduling: array<empty>|list<array{id: ?string, messageId: string, method: string, contents: string}>,
- *     attachments: array<empty>|list<array{id: int<1, max>, messageId: int<1, max>, filename: string, mime: string, size: int<0, max>, cid: ?string, disposition: string, downloadUrl?: string}>
+ *     scheduling: list<array{id: ?string, messageId: string, method: string, contents: string}>,
+ *     attachments: list<array{id: int<1, max>, messageId: int<1, max>, filename: string, mime: string, size: int<0, max>, cid: ?string, disposition: string, downloadUrl?: string}>
  * }
  *
- * @psalm-type MessageApiResponse = MailIMAPFullMessage&array{
+ * @psalm-type MailMessageApiResponse = MailIMAPFullMessage&array{
  *     signature: ?string,
- *     itineraries?: array{},
+ *     itineraries?: array<string, mixed>,
  *     id: int<1, max>,
  *     isSenderTrusted: bool,
  *     smime: array{ isSigned: bool, signatureIsValid: ?bool, isEncrypted: bool},
  *     dkimValid?: bool,
  *     rawUrl: string
  * }
  *
- * @psalm-type MessageApiAttachment = array{ name: string, mime: string, size: int<0, max>, content: string}
+ * @psalm-type MailMessageApiAttachment = array{ name: string, mime: string, size: int<0, max>, content: string}
  */
 class ResponseDefinitions {
 }

vendor-bin/openapi/composer.json

@@ -0,0 +1,17 @@
+{
+	"config": {
+		"platform": {
+			"php": "8.1"
+		},
+		"sort-packages": true
+	},
+	"require": {
+		"nextcloud/openapi-extractor": "dev-main"
+	},
+	"repositories": [
+		{
+			"type": "vcs",
+			"url": "https://github.com/nextcloud/openapi-extractor"
+		}
+	]
+}