feat: Isomorphic SDKs

[ChiragAgg5k]

Summary

Implements the isomorphic SDK client pattern across the generated Web, Flutter, and Apple 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 into one PR.

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.

Backwards Compatibility

Existing constructor/setter setup remains supported in all three 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>")

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 and static factories to Web, Flutter, and Apple client templates.
• Keeps service construction syntax unchanged across all three SDKs.
• Hides service .client internals from the public generated service surface.
• 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
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

[greptile-apps]

Greptile Summary

This PR introduces a typed factory pattern (ClientAuth protocol / abstract class / branded type) across Apple, Flutter, and Web SDK generator templates, replacing the imperative Client().setX().setY() chain with explicit Client.fromBrowser, Client.fromSession, Client.fromDevKey, and Client.fromImpersonation constructors. Legacy setters are preserved but deprecated.

• Apple: Adds ClientAuth protocol, four static factories on Client, private configure/setHeader helpers, a new apple/base/params.twig that reads auth values via getConfig(key:), and updates generated services and Realtime to accept and store ClientAuth.
• Flutter: Splits the existing Client abstract into ClientAuth (minimal protocol) and Client (legacy setters + factory statics), mirrors the four factory methods using createClient() internally, and guards RealtimeBrowser/RealtimeIO with runtime type checks.
• Web: Introduces a ClientRuntime<TAuth> class with a phantom TAuth brand, a ClientConstructor type that exposes only factory statics, and per-service Omit-based types that hide internal methods from consumers.

Confidence Score: 5/5

The change is additive and backwards-compatible — existing Client() setter chains continue to compile alongside the new factory methods.

No regressions were found in the core factory logic, auth header propagation, or service construction. The design notes around endpoint fatalError and the Flutter Realtime runtime type check are pre-existing patterns or intentional guards rather than new defects introduced by this PR.

templates/apple/Sources/Client.swift.twig — endpoint and realtime URL validation still uses fatalError even though fromImpersonation was updated to throw; worth aligning them if the factory surface is meant to be fully throwable for invalid inputs.

Important Files Changed

Filename	Overview
templates/apple/Sources/Client.swift.twig	Adds ClientAuth protocol and four factory methods; endpoint validation still uses fatalError instead of throwing, inconsistent with the fromImpersonation fix.
templates/apple/Sources/Service.swift.twig	New base Service class whose init accepts but does not store ClientAuth; relies entirely on subclass overrides to retain the client reference.
templates/apple/Sources/Services/Service.swift.twig	Generated services now store _client: ClientAuth themselves and include apple/base/params.twig which reads auth values through getConfig(key:).
templates/apple/Sources/Services/Realtime.swift.twig	Realtime now stores ClientAuth directly and accesses project via getConfig(key:) instead of direct config dict access.
templates/flutter/lib/src/client.dart.twig	Splits the single Client abstract class into ClientAuth (protocol surface) and Client (legacy setters); adds four factory constructors mirroring the Apple/Web pattern.
templates/flutter/lib/src/realtime_browser.dart.twig	Accepts ClientAuth but immediately throws ArgumentError for non-ClientBrowser instances, creating a mismatch between declared and required type.
templates/flutter/lib/src/realtime_io.dart.twig	Same pattern as realtime_browser.dart.twig: accepts ClientAuth but throws for non-ClientIO instances at runtime.
templates/web/src/client.ts.twig	Introduces ClientRuntime class with branded TAuth type parameter, static factory methods, and a TypeScript ImpersonationTarget discriminated union that enforces single-target constraint at compile time.
templates/web/src/services/template.ts.twig	Generated services now use Client<TAuth> for mixed-tier, server-only, or client-only auth shapes, hiding internal client from the public type surface.

_{Reviews (3): Last reviewed commit: "Merge Flutter isomorphic SDK changes" | Re-trigger Greptile}

[ChiragAgg5k]

Superseded by #1512, which uses the clearer branch for the consolidated isomorphic SDK changes.