Add Lemmy 1.0.0 support

.github/workflows/ci.yml

@@ -18,18 +18,15 @@ jobs:
         os: [ macos-latest, ubuntu-latest, windows-latest ]
 
     steps:
-      - uses: actions/checkout@v4
-      - uses: SimonMarquis/ci-gradle-properties-action@v1
-        with:
-          path: .github/gradle.properties
-      - uses: actions/setup-java@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
           java-version: '17'
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v3
+        uses: gradle/actions/setup-gradle@v5
       - name: Cache Konan dependencies
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.konan
           key: ${{ runner.os }}-konan-${{ hashFiles('**/*.gradle.kts') }}
@@ -40,10 +37,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v3
-      - uses: actions/setup-java@v4
+        uses: gradle/actions/setup-gradle@v5
+      - uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
           java-version: '17'
@@ -52,13 +49,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
-      - uses: SimonMarquis/ci-gradle-properties-action@v1
-        with:
-          path: .github/gradle.properties
+      - uses: actions/checkout@v6
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v3
-      - uses: actions/setup-java@v4
+        uses: gradle/actions/setup-gradle@v5
+      - uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
           java-version: '17'

.github/workflows/deploy.yml

@@ -3,14 +3,17 @@ name: Deployment
 on:
   push:
     tags: [ '[0-9]+.[0-9]+.[0-9]+*' ]
+  workflow_dispatch:
 
 jobs:
   publish:
-    if: github.repository == 'mv-gh/lemmybackwardscompatibleapi' && startsWith(github.ref, 'refs/tags')
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ macos-latest, ubuntu-latest, windows-latest ]
+    if: >
+      github.repository == 'mv-gh/lemmybackwardscompatibleapi' &&
+      (
+        startsWith(github.ref, 'refs/tags/') ||
+        (github.event_name == 'workflow_dispatch' && github.actor == 'mv-gh')
+      )
+    runs-on: macos-latest
     environment: publish
     env:
       ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.ORG_GRADLE_PROJECT_signingInMemoryKey }}
@@ -19,13 +22,10 @@ jobs:
       ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.ORG_GRADLE_PROJECT_mavenCentralPassword }}
       ORG_GRADLE_PROJECT_signingInMemoryKeyId: ${{ secrets.ORG_GRADLE_PROJECT_signingInMemoryKeyId }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: SimonMarquis/ci-gradle-properties-action@v1
-        with:
-          path: .github/gradle.properties
+      - uses: actions/checkout@v6
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v3
-      - uses: actions/setup-java@v4
+        uses: gradle/actions/setup-gradle@v5
+      - uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
           java-version: '17'

ACTIVE_CHANGES.md

@@ -3,6 +3,37 @@
 This document lists the changes that you will need to actively handle, through feature flags.
 
 
+## V1
+
+### Sort types split + `time_range_seconds`
+
+The many `Top*` `SortType` variants (`TopDay`, `TopWeek`, `TopMonth`, `TopYear`, `TopAll`, `TopHour`, `TopSixHour`, `TopTwelveHour`, `TopThreeMonths`, `TopSixMonths`, `TopNineMonths`) have been collapsed into a single `Top` value in v1. Time range is now expressed via `time_range_seconds: Long?` on the query (`GetPosts`, `GetComments`, `ListCommunities`, `ListMultiCommunities`, `Search`).
+
+- On v1, set `sort = SortType.Top` and pass `time_range_seconds` (e.g. `86400` for top day).
+- On pre-v1, the old `Top*` variants are still used; `time_range_seconds` is ignored. The wrapper translates automatically.
+
+### Image upload / delete compatibility
+
+- Consumers should use `LemmyApiBaseController.uploadImage()` and `LemmyApiBaseController.deleteMedia()`.
+- Pre-1.0 Lemmy instances are now wired internally to legacy pictrs endpoints; callers should not use pictrs APIs directly anymore.
+- `UploadImageResponse` now includes `delete_filename`.
+- Always pass `uploadImage(...).delete_filename` into `deleteMedia(DeleteImageParams(...))`.
+- On Lemmy `1.x`, `delete_filename == filename`.
+- On pre-`1.0`, `delete_filename` contains the full legacy pictrs delete path, like `/pictrs/image/delete/{delete_token}/{file}`.
+
+### Avatar/Icon/Banner
+
+Should now use the dedicated avatar/icon/banner upload/delete endpoints.
+
+### Pagination: `page` replaced by `page_cursor`
+
+`page: Long?` has been removed from all list/query types in v1 (`GetPosts`, `GetComments`, `GetModlog`, `Search`, `ListCommunities`, `ListReports`, `ListNotifications`, `ListMedia`, `ListPersonContent`, `ListPostLikes`, `ListCommentLikes`, `ListRegistrationApplications`).
+
+- On v1, use `page_cursor` for cursor-based pagination.
+- To support pre-v1 instances, populate **both** `page` (for older versions, handled internally) and `page_cursor` (for v1). The wrapper will pass the appropriate one.
+
+
+
 ## 0.19.11
 
 - Added `last_donation_notification` field to LocalUser
@@ -29,4 +60,3 @@ But each has different behaviour. The old behaviour is to hide all voting types
 - Log out support (invalidates the current JWT)
 - Instance block support
 - 2FA rework, one must now provide a valid 2FA code to enable 2FA. Added routes to support this.
-

CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to this project
+
+
+## Architecture
+
+```
+LemmyApiClient (options, optional caller-owned HttpClient)
+  └─ connect / connectForVersion (typed instance, auth, version) → LemmyApiBaseController
+        │
+        └─ version-specific LemmyApiUniWrapper  (implements LemmyApiBaseController)
+              ├─ LemmyApiController              (raw Ktor HTTP calls, version-specific datatypes)
+              ├─ Transformer                     (maps version-specific ↔ unified datatypes)
+              └─ MapperGenerator (interface)     (declares all toUni/fromUni signatures)
+```
+
+### Per-version module structure
+
+Each `vX/xN/xM/` folder contains exactly these files:
+
+| File | Purpose |
+|---|---|
+| `datatypes/` | Auto-generated version-specific Kotlin datatypes. **Do not edit by hand.** |
+| `MapperGenerator.kt` | Interface declaring all `toUni` / `fromUni` signatures, used to drive Konvert code generation. Annotations are commented out in committed code; uncomment + build to regenerate. |
+| `Transformer.kt` | Implements `MapperGenerator`. Contains all field-level mapping logic. Generated initially by Konvert, then hand-maintained for non-trivial differences. |
+| `LemmyApiUniWrapper.kt` | Implements `LemmyApiBaseController`. Delegates HTTP calls to `LemmyApiController` and transforms results. Unsupported endpoints call `notSupported()`. |
+| `LemmyApiController.kt` | Raw Ktor HTTP calls returning version-specific datatypes. |
+| `LemmyApiRouter.kt` | Route path definitions for this version. |
+
+### Unified datatypes (1.0.0 baseline)
+
+The `it.vercruysse.lemmyapi.datatypes` package represents the **1.0.0 Lemmy API** and is the single source of truth for all API consumers. Older version wrappers transform their version-specific types into these unified types. See `ACTIVE_CHANGES.md` for the key API differences consumers need to handle.
+
+
+## Backwards Compatibility Strategy
+
+- **API route added**: add a function to `FeatureFlags` that returns whether this feature is supported. Older versions implement this route by throwing `notSupported()`.
+- **API route removed**: newer versions implement the old route by throwing `notSupported()`. Add to the `oldRoutes` interface if needed.
+- **Request/response changes**: transform using `Transformer`. The unified type (usually the latest datatype shape) is returned regardless of version. Example: [moving admin flag from person to local_user](https://github.com/LemmyNet/lemmy/pull/3403) — pre-0.19 APIs map their type to the latest shape.
+- **Enum entries**: each entry tracks `minimumVersion`/`maximumVersion`. Use `getSupportedEntries<Type>()` to retrieve the valid entries for the connected instance (e.g. sort options).
+
+
+## Compatibility Rules
+
+When adding or updating an older-version implementation:
+
+1. **Reference `v0.x19.x11`** — it is kept up-to-date with the unified interface. Copy its `LemmyApiUniWrapper.kt` pattern.
+2. `MapperGenerator.kt` return types must use **unified** types only.
+3. `Transformer.kt` must not import deleted unified types.
+4. `LemmyApiUniWrapper.kt` must implement **every** abstract method from `LemmyApiBaseController`. Missing features use `notSupported()`.
+5. Import aliases are required in `Transformer.kt`:
+   - Unified types: `import it.vercruysse.lemmyapi.datatypes.Foo as LemmyapiDatatypesFoo`
+   - Local version types: `import it.vercruysse.lemmyapi.vX.xN.xM.datatypes.Foo as XMDatatypesFoo`
+   - Unused aliases cause compilation errors — remove them when the corresponding method is deleted.
+
+
+## AutoGenerated Code
+
+To minimize the maintenance burden, many aspects have been automated via Kotlin scripts in the `GeneratorScripts` submodule:
+
+- **`GenTypes`**: Downloads TS types from [lemmy-js-client](https://github.com/LemmyNet/lemmy-js-client) and generates `datatypes/` for a target version. Requires [dukat](https://github.com/Kotlin/dukat).
+- **`GenRoutes`**: Generates route/controller templates from [lemmy_openapi_spec](https://github.com/MV-GH/lemmy_openapi_spec). Output goes to `temp/`.
+- **`GenMapperRoutes`**: Generates `MapperGenerator.kt` by diffing two version datatypes. Uncomment the Konvert annotations and build to generate `Transformer.kt` base, then copy from the build output. Output goes to `temp/`.
+
+See `STEPS_TO_SUPPORT_MORE_VERSION.md` for the full checklist when adding a new Lemmy version.
+

GeneratorScripts/build.gradle.kts

@@ -1,7 +1,7 @@
 plugins {
     kotlin("jvm")
-    kotlin("plugin.serialization") version "2.1.10"
-    id("com.google.devtools.ksp").version("2.1.10-1.0.30")
+    kotlin("plugin.serialization") version "2.3.21"
+    id("com.google.devtools.ksp").version("2.3.8")
 }
 
 repositories {
@@ -11,19 +11,18 @@ repositories {
 dependencies {
     testImplementation("org.jetbrains.kotlin:kotlin-test")
     implementation("com.charleskorn.kaml:kaml:0.55.0")
-    val ktorVersion = "3.1.2"
-    val konvertVersion = "3.2.1"
+    val ktorVersion = "3.5.0"
+    val konvertVersion = "4.5.0"
     implementation("io.ktor:ktor-client-core:$ktorVersion")
     implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
     implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
     implementation("io.ktor:ktor-client-logging:$ktorVersion")
 
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
-    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.1")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")
 
-    implementation("com.squareup.okio:okio:3.10.2")
-    implementation("org.jetbrains.kotlinx:kotlinx-io-core:0.6.0")
-    implementation("io.mcarle:konvert:$konvertVersion")
+    implementation("com.squareup.okio:okio:3.17.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-io-core:0.9.0")
     implementation("io.mcarle:konvert-api:$konvertVersion")
     implementation(project(":app"))
 
@@ -37,3 +36,4 @@ tasks.test {
 kotlin {
     jvmToolchain(17)
 }
+