feat(spec update) Update the spec and upgrade Jane

.github/workflows/tests.yml

@@ -19,24 +19,26 @@ jobs:
       - name: Setup
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.0'
+          php-version: 8.3
           extensions: mbstring, fileinfo, json, intl, dom
+          tools: castor
 
       - name: Run composer install
         run: composer install -n --prefer-dist
 
-      - name: 'php-cs-fixer check'
-        run: 'vendor/bin/php-cs-fixer fix --dry-run --diff'
-        env:
-          PHP_CS_FIXER_IGNORE_ENV: 1
+      - name: Install qa tooling
+        run: castor qa:update
+
+      - name: Check coding standards
+        run: castor qa:cs --dry-run
 
   tests:
     name: Run tests for PHP ${{ matrix.php-versions }}
     runs-on: ubuntu-latest
     strategy:
       max-parallel: 15
       matrix:
-        php-versions:  ['8.0', '8.1', '8.2']
+        php-versions:  ['8.1', '8.2', '8.3']
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -52,9 +54,10 @@ jobs:
         with:
           php-version: ${{ matrix.php-versions }}
           extensions: mbstring, fileinfo, json, intl, dom
+          tools: castor
 
       - name: Run composer install
         run: composer install -n --prefer-dist
 
       - name: Run tests
-        run: make test
+        run: castor qa:test

.gitignore

@@ -1,3 +1,6 @@
+# Castor
+/.castor.stub.php
+
 # Composer
 composer.lock
 composer.phar

CHANGELOG.md

@@ -1,23 +1,30 @@
 # Changes between versions
 
+## 7.0.0 (2024-03-29)
+
+ * upgrade to `janephp/open-api` 7.6
+ * drop support for PHP <8.1
+ * update the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#28 in #47
+ * switch to [Castor](https://castor.jolicode.com/) for the project tooling
+
 ## 6.3.0 (2023-08-17)
 
- * updated the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#27 in #44
-   * updated the spec according to the current documentation
-   * fixed several definitions
+ * update the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#27 in #44
+   * update the spec according to the current documentation
+   * fix several definitions
 
 ## 6.2.0 (2023-04-19)
 
  * upgrade to `janephp/open-api` 7.4
- * updated the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#26 in #43
+ * update the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#26 in #43
    * support for the newly introduced pagination cursors
-   * updated descriptions according to the docs
+   * update descriptions according to the docs
    * add `TimeReportsResult.weekly_capacity` and `TimeReportsResult.avatar_url`
  * bump the minimum required PHP version
 
 ## 6.1.0 (2022-11-12)
 
- * updated the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#22 in #41
+ * update the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#22 in #41
    * add support for `User.access_roles` as defined in https://help.getharvest.com/api-v2/users-api/users/users/#access-roles
    * remove the now non-working `User.is_admin` and `User.is_project_manager` booleans
    * add management of users assigned team mates, as defined in https://help.getharvest.com/api-v2/users-api/users/teammates/
@@ -27,28 +34,28 @@
 
  * upgrade to `janephp/open-api` 7.3
  * drop support for PHP <7.4
- * updated the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#20
-   * added `Company.currency_code_display` and `Company.currency_symbol_display`
-   * several fields of the `User` object have disappeared, due to the [API changes introduced in March](https://www.getharvest.com/blog/new-flexible-permissions#:~:text=The%20API%20has%20been%20updated%20to%20align%20with%20the%20new%20permissions%20features.).
+ * update the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#20
+   * add `Company.currency_code_display` and `Company.currency_symbol_display`
+   * several fields of the `User` object have disappeared, due to the [API changes introduced in March](https://www.getharvest.com/blog/new-flexible-permissions#:~:text=The%20API%20has%20been%20update%20to%20align%20with%20the%20new%20permissions%20features.).
 
 ## 5.2.0 (2022-01-10)
 
- * upgraded `janephp/open-api` from 6.3 to 7.1 - thanks @jdrieghe
- * added support for Symfony 6
- * updated the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#19
-   * added support for `User.telephone`
+ * upgrade `janephp/open-api` from 6.3 to 7.1 - thanks @jdrieghe
+ * add support for Symfony 6
+ * update the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#19
+   * add support for `User.telephone`
 
 ## 5.1.0 (2021-08-03)
 
- * updated the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#18
-   * added `date_format` on the `Company` model
-   * added `hours_without_timer` and `external_reference/account_id` in the `TaskAssignment` model
+ * update the SDK based on the latest spec updates - see jolicode/harvest-openapi-generator#18
+   * add `date_format` on the `Company` model
+   * add `hours_without_timer` and `external_reference/account_id` in the `TaskAssignment` model
 
 ## 5.0.0 (2021-04-10)
 
  * add tests on the API
  * support PHP 7.2 to PHP 8.0
- * migrated the openapi spec to open api 3
+ * migrate the openapi spec to open api 3
 
 ## 4.3.0 (2021-01-18)
 
@@ -64,55 +71,55 @@
 
  * use Jane 6 Authentication plugins
  * upgrade to `janephp/open-api` 6.1
- * regenerated SDK
- * fixed the `jane-php/open-api-runtime` dependency to a minor version, in order to avoid situations where a jane-php update would break things
+ * regenerate SDK
+ * fix the `jane-php/open-api-runtime` dependency to a minor version, in order to avoid situations where a jane-php update would break things
 
 ## 4.0.1 (2020-07-30)
 
  * upgrade to `janephp/open-api` 6.0
- * fixed boolean query parameters serialization
+ * fix boolean query parameters serialization
 
 ## 4.0.0 (2020-05-14)
 
- * fixed several endpoint names
- * removed missnamed endpoints
+ * fix several endpoint names
+ * remove missnamed endpoints
  * [documented all the available operations](doc/index.md)
 
 ## 3.0.3 (2020-02-25)
 
- * fixed plural definition names for reports Schemas
+ * fix plural definition names for reports Schemas
 
 ## 3.0.2 (2020-02-25)
 
- * Added Schemas for the "reports" endpoints
+ * add Schemas for the "reports" endpoints
 
 ## 3.0.1 (2020-02-25)
 
- * fixed the location of reports endpoints parameters
+ * fix the location of reports endpoints parameters
 
 ## 3.0.0 (2020-02-21)
 
  * upgrade to `janephp/open-api` 5.3
- * updated the SDK based on the latest [spec updates](https://github.com/jolicode/harvest-openapi-generator/pull/9):
+ * update the SDK based on the latest [spec updates](https://github.com/jolicode/harvest-openapi-generator/pull/9):
    * add the ability to filter time entries by `task_id`
    * several new "report" endpoints
    * support for `rounded_hours` in the `TimeEntry` model
 
 ## 2.1.0 (2020-01-14)
 
- * updated the OpenAPI definition file
- * added the "company update" endpoint
- * updated the endpoints documentation according to Harvest's API doc
- * added the `Company` `weekly_capacity` attribute
- * added the `Invoice` `recurring_invoice_id` attribute
+ * update the OpenAPI definition file
+ * add the "company update" endpoint
+ * update the endpoints documentation according to Harvest's API doc
+ * add the `Company` `weekly_capacity` attribute
+ * add the `Invoice` `recurring_invoice_id` attribute
 
 ## 2.0.0 (2019-10-28)
 
- * Upgrade Jane to 4.5 https://github.com/janephp/janephp/releases/tag/v4.5.3, the new generated classes have better PHPDoc​
- * Generate PSR-18 client instead of HttPlug client
- * Support for cost and billable rates
- * Removed the telephone property from the user model
- * Added statement_key in the Client properties
+ * upgrade Jane to 4.5 https://github.com/janephp/janephp/releases/tag/v4.5.3, the new generated classes have better PHPDoc​
+ * generate PSR-18 client instead of HttPlug client
+ * support for cost and billable rates
+ * remove the telephone property from the user model
+ * add statement_key in the Client properties
 
 ## 1.1.0 (2019-04-01)
 
@@ -121,11 +128,11 @@
 ## 1.0.2 (2019-01-24)
 
  * support null values for nested objects or values (jane-openapi strict mode false)
- * changed `quantity` types to `float` instead of `integer`
+ * change `quantity` types to `float` instead of `integer`
 
 ## 1.0.1 (2019-01-22)
 
- * Fixed the `deleteTimeEntryExternalReference` endpoint operationId
+ * fix the `deleteTimeEntryExternalReference` endpoint operationId
 
 ## 1.0.0 (2019-01-21)
 

CONTRIBUTING.md

@@ -48,7 +48,7 @@ Use [PHP CS fixer](http://cs.sensiolabs.org/) to make your code compliant with
 our coding standards:
 
 ```shell
-make cs
+castor qa:cs
 ```
 
 ## Keeping your fork up-to-date

Resources/harvest-openapi.yaml

@@ -1044,7 +1044,7 @@ components:
           nullable: true
         is_closed:
           type: boolean
-          description: 'Whether the expense has been approved or closed for some other reason.'
+          description: 'Whether the expense has been approved or not.'
           nullable: true
         is_locked:
           type: boolean
@@ -1293,7 +1293,7 @@ components:
           nullable: true
         timer_started_at:
           type: string
-          description: 'Date and time the timer was started (if tracking by duration). Use the ISO 8601 Format.'
+          description: 'Date and time the running timer was started (if tracking by duration). Use the ISO 8601 Format. Returns null for stopped timers.'
           nullable: true
           format: date-time
         started_time:
@@ -7330,6 +7330,10 @@ paths:
                   type: string
                   description: 'Any notes to be associated with the payment.'
                   nullable: true
+                send_thank_you:
+                  type: boolean
+                  description: 'Whether or not to send a thank you email (if enabled for your account in Invoices > Configure > Messages). Only sends an email if the invoice will be fully paid after creating this payment. Defaults to true.'
+                  nullable: true
               required:
                 - amount
   '/invoices/{invoiceId}/payments/{paymentId}':
@@ -9126,6 +9130,13 @@ paths:
           in: query
           schema:
             type: string
+        -
+          name: include_fixed_fee
+          description: 'When true, billable amounts will be calculated and included for fixed fee projects.'
+          required: false
+          in: query
+          schema:
+            type: string
         -
           name: page
           description: 'The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)'
@@ -9220,6 +9231,13 @@ paths:
           in: query
           schema:
             type: string
+        -
+          name: include_fixed_fee
+          description: 'When true, billable amounts will be calculated and included for fixed fee projects.'
+          required: false
+          in: query
+          schema:
+            type: string
         -
           name: page
           description: 'The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)'
@@ -9322,6 +9340,13 @@ paths:
           in: query
           schema:
             type: string
+        -
+          name: include_fixed_fee
+          description: 'When true, billable amounts will be calculated and included for fixed fee projects.'
+          required: false
+          in: query
+          schema:
+            type: string
         -
           name: page
           description: 'The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)'
@@ -9419,6 +9444,13 @@ paths:
           in: query
           schema:
             type: string
+        -
+          name: include_fixed_fee
+          description: 'When true, billable amounts will be calculated and included for fixed fee projects.'
+          required: false
+          in: query
+          schema:
+            type: string
         -
           name: page
           description: 'The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)'

castor.php

@@ -0,0 +1,64 @@
+<?php
+
+/*
+ * This file is part of JoliCode's Harvest PHP API project.
+ *
+ * (c) JoliCode <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace sdk;
+
+use Castor\Attribute\AsTask;
+
+use function Castor\exit_code;
+use function Castor\fs;
+use function Castor\import;
+use function Castor\io;
+use function Castor\request;
+
+import(__DIR__.'/tools/php-cs-fixer/castor.php');
+
+const SPEC_URL = 'https://raw.githubusercontent.com/jolicode/harvest-openapi-generator/master/generated/harvest-openapi.yaml';
+
+#[AsTask(description: 'Downloads the last specification and re-generates the SDK', aliases: ['update'])]
+function update(): int
+{
+    update_specification();
+
+    return generate();
+}
+
+#[AsTask(description: 'Downloads the last specification from Github')]
+function update_specification(): void
+{
+    io()->comment(sprintf('Download the spec from %s', SPEC_URL));
+    fs()->dumpFile(
+        'Resources/harvest-openapi.yaml',
+        request('GET', SPEC_URL)->getContent()
+    );
+    io()->success('Successfully updated the OpenAPI specification file.');
+}
+
+#[AsTask(description: 'Re-generates the SDK using the local specification')]
+function generate(): int
+{
+    io()->comment('Generating the SDK using Jane OpenAPI...');
+    $result = exit_code('./vendor/bin/jane-openapi generate -c .jane-openapi.php');
+
+    if (0 !== $result) {
+        io()->error('An error occurred while generating the SDK.');
+    } else {
+        io()->success('Successfully generated the SDK');
+    }
+
+    return $result;
+}
+
+#[AsTask(description: 'Runs the test suite', namespace: 'qa')]
+function test(): int
+{
+    return exit_code('./vendor/bin/simple-phpunit');
+}