feat: Isomorphic SDKs

[ChiragAgg5k]

Summary

Implements the isomorphic SDK client pattern across the generated Web, Flutter, Apple, and Android SDKs. Each SDK now exposes explicit auth factory methods for the recommended setup path while preserving the existing Client() constructor and setter style for backwards compatibility.

This consolidates the work from #1481, #1510, and #1511, and extends the same client SDK pattern to Android.

Web SDK

The generated Web SDK now uses one typed generic Client across browser, server, and console output. Static factories describe both runtime and auth capability, and generated services narrow their available methods from the client auth type.

import { Client, Account, TablesDB } from 'appwrite';

const browserClient = Client.fromBrowser({
  endpoint: 'https://<REGION>.cloud.appwrite.io/v1',
  projectId: '<PROJECT_ID>',
});

const serverClient = Client.fromAPIKey({
  endpoint: 'https://<REGION>.cloud.appwrite.io/v1',
  projectId: '<PROJECT_ID>',
  apiKey: '<API_KEY>',
});

new Account(browserClient);              // OK
new TablesDB(browserClient).createRow;   // OK
new TablesDB(browserClient).createTable; // Type error for browser auth
new TablesDB(serverClient).createTable;  // OK

Available Web factories include fromBrowser, fromSession, fromDevKey, fromImpersonation, fromAPIKey, fromJWT, and fromCookie, with server-only factories omitted from client-platform output.

Flutter SDK

The generated Flutter client SDK now exposes a ClientAuth interface returned by factory-created clients. Services and Realtime accept ClientAuth, so the construction syntax stays the same while legacy setters are hidden from factory-created clients.

import 'package:appwrite/appwrite.dart';

final client = Client.fromBrowser(
  endPoint: 'https://<REGION>.cloud.appwrite.io/v1',
  projectId: '<PROJECT_ID>',
);

Account(client);      // OK
Realtime(client);     // OK
client.setProject('other'); // Analyzer error

Available Flutter factories are fromBrowser, fromSession, fromDevKey, and fromImpersonation. This is intentionally scoped to Flutter client output and does not add server auth factories to Flutter.

Apple SDK

The generated Apple SDK now exposes a ClientAuth protocol returned by factory-created clients. Generated services and Realtime accept ClientAuth, and services read auth values through getConfig(key:) instead of exposing the raw config dictionary.

let client = Client.fromBrowser(
    projectId: "<PROJECT_ID>"
)

let sessionClient = Client.fromSession(
    projectId: "<PROJECT_ID>",
    session: "<SESSION>"
)

let tables = TablesDB(client)
let realtime = Realtime(client)

Available Apple factories are fromBrowser, fromSession, fromDevKey, and throwing fromImpersonation. All factories accept optional endpoint, realtime endpoint, locale, self-signed, and compression values. fromImpersonation throws an AppwriteError when callers pass zero or multiple impersonation targets.

Android SDK

The generated Android SDK now exposes a ClientAuth interface returned by factory-created clients. Generated services and Realtime accept ClientAuth, while the legacy concrete Client keeps the existing constructor and setter surface.

import io.appwrite.Client
import io.appwrite.services.Account
import io.appwrite.services.Realtime

val client = Client.fromBrowser(
    context = context,
    projectId = "<PROJECT_ID>",
    endpoint = "https://<REGION>.cloud.appwrite.io/v1"
)

Account(client)   // OK
Realtime(client)  // OK
client.setProject("other") // Compile error on ClientAuth

Available Android factories are fromBrowser, fromSession, fromDevKey, and fromImpersonation. Factories accept optional endpoint, realtime endpoint, locale, and self-signed values. fromImpersonation validates that exactly one of userId, userEmail, or userPhone is provided.

Backwards Compatibility

Existing constructor/setter setup remains supported in all four SDKs:

const webClient = new Client()
  .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
  .setProject('<PROJECT_ID>');

final flutterClient = Client()
  ..setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
  ..setProject('<PROJECT_ID>');

let appleClient = Client()
    .setEndpoint("https://cloud.appwrite.io/v1")
    .setProject("<PROJECT_ID>")

val androidClient = Client(context)
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<PROJECT_ID>")

Those legacy setters are marked deprecated and remain available from direct Client() instances. Factory-created clients intentionally expose the narrower auth surface.

Implementation Notes

• Adds auth capability typing/protocols/interfaces and static factories to Web, Flutter, Apple, and Android client templates.
• Keeps service construction syntax unchanged across all four SDKs.
• Hides service .client internals from the public generated service surface where supported by the SDK language.
• Updates Realtime templates to accept factory-created clients.
• Marks legacy setters as deprecated without removing them.
• Generates Web factory base params from spec-backed global headers instead of hardcoded template branches.
• Adds SDK build validation coverage for the combined generated surfaces.

Validation

Ran on the consolidated branch:

php example.php web server
php example.php web client
php example.php web console
php example.php flutter client
php example.php apple client
php example.php android client
composer lint-twig
php -l src/SDK/Language/Web.php
php -l src/SDK/Language/Flutter.php
php -l src/SDK/Language/Apple.php
git diff --check origin/master...HEAD
sh ./gradlew :library:compileDebugKotlin # from examples/android

Android compilation succeeded after Gradle fell back from the Kotlin daemon. The daemon failed locally because the installed Java version reports as 25.0.2; the non-daemon compiler completed successfully with existing generated-code warnings.

[greptile-apps]

Greptile Summary

This PR adds isomorphic auth factory methods (fromBrowser, fromSession, fromDevKey, fromImpersonation, and server-side variants) across Web, Flutter, Apple, Android, Kotlin, Dart, Node, and React Native SDK templates. Existing Client() constructor and setter patterns remain available and are marked deprecated where applicable.

• Auth interfaces/protocols (ClientAuth) are introduced for Flutter, Apple, and Android so services and Realtime accept factory-created clients without exposing legacy setter surface; the Web template uses a brand-typed generic ClientRuntime<TAuth> with a ClientConstructor cast.
• Realtime templates (Flutter browser and IO) drop unsafe is! ClientBrowser runtime casts in favour of delegating WebSocket creation through a new realtimeWebSocket method on ClientAuth.
• Validation (endpoint URL format, realtime URL prefix, impersonation target count) is consistently applied at factory call time across all platforms; the Web template also fixes a long-standing realtime heartbeat bug (clearTimeout → clearInterval) and guards all window access for SSR compatibility.

Confidence Score: 5/5

The change is safe to merge; all previously flagged issues have been addressed and factory implementations are consistent across platforms.

Every issue from prior review rounds is resolved: endpoint URL validation is present in all factory paths, config entries are written alongside headers, the Flutter Realtime is! cast is gone, and fromImpersonation throws the correct exception type in every SDK. The one remaining observation about React Native is a design question rather than a functional defect.

templates/react-native/src/client.ts.twig — the factory set is inconsistent with the Node template (fromAPIKey and fromJWT absent, fromCookie present).

Important Files Changed

Filename	Overview
templates/web/src/client.ts.twig	Introduces isomorphic client with brand-typed generic ClientRuntime and ClientConstructor cast; adds all seven static factories with correct header/config writes; fixes realtime heartbeat from clearTimeout to clearInterval; guards window access for SSR compatibility
templates/web/src/services/template.ts.twig	Service now emits ServiceRuntime class plus Service type alias; webMethodAuthReceiver filter is properly wired and generates this-receiver constraints for mixed-tier services
templates/flutter/lib/src/client.dart.twig	Splits Client abstract class into ClientAuth interface and legacy Client; factories validate endpoint and realtime endpoint; fromImpersonation now throws AppwriteException consistently
templates/flutter/lib/src/realtime_browser.dart.twig	Dropped unsafe is! ClientBrowser runtime cast; Realtime delegates WebSocket creation to client.realtimeWebSocket
templates/apple/Sources/Client.swift.twig	Adds ClientAuth protocol and four factory methods; auth values stored in both config and headers via setHeader helper; configureConnection only recreates HTTP client when selfSigned or compression changes
templates/android/library/src/main/java/io/package/Client.kt.twig	Adds ClientAuth interface with callInternal/chunkedUploadInternal; four factory methods with require() guards; setHeader helper writes both camelCase and lowercase config keys
templates/react-native/src/client.ts.twig	Adds five factory methods with correct config+headers writes; fromAPIKey and fromJWT absent while fromCookie is present
templates/dart/lib/src/client.dart.twig	Adds all seven factory methods; _fromBase calls ..setEndpoint() which validates the URL; both camelCase and lowercase config keys populated
src/SDK/Language/Web.php	Adds webServiceAuth, webMethodAuthReceiver, webClientBaseParams, webClientConfigKeys, and webClientSetterReturnType filters; all filters properly registered
tests/Base.php	Adds CLIENT_AUTH_FACTORY_RESPONSES, SERVER_AUTH_FACTORY_RESPONSES, and ISOMORPHIC_AUTH_FACTORY_RESPONSES constants covering all factory outputs including validation errors

_{Reviews (17): Last reviewed commit: "Mirror Swift auth factories into config" | Re-trigger Greptile}