Unify web SDK Client auth factories

[ChiragAgg5k]

Summary

Refactors the generated Web SDK so browser, server, and console usage share one typed Client class with explicit static auth factories. The factories describe both runtime behavior and auth capability while preserving the existing constructor/setter style for compatibility.

The recommended browser setup is now:

import { Client, Account } from 'appwrite';

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

const account = new Account(client);

The old syntax is still supported:

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

Those legacy set* methods are now marked @deprecated and are only visible from new Client(). Factory-created clients do not expose legacy setters.

Auth Factories

All factories take object params. Common fields include endpoint, projectId, endpointRealtime, locale, and selfSigned. Spec-backed base params such as projectId, locale, mode, and platform are generated from spec.global.headers via Web language filters instead of hardcoded template branches.

Available factories:

Factory	Auth/runtime	Notes
Client.fromBrowser(...)	browser/client	Normal browser apps; cookies may authenticate the current user automatically.
Client.fromSession(...)	session/client	Sends X-Appwrite-Session; useful when a session secret is explicitly available.
Client.fromDevKey(...)	dev key/client	Client-tier dev key usage.
Client.fromImpersonation(...)	impersonation/client	Requires session and exactly one of userId, email, or phone.
Client.fromAPIKey(...)	API key/server	Trusted server-side code only. Not emitted for client-platform builds.
Client.fromJWT(...)	JWT/server	Trusted server-side code using X-Appwrite-JWT. Not emitted for client-platform builds.
Client.fromCookie(...)	cookie/server	For SSR cookie forwarding and console runtime. Console builds default mode to admin.

Type Safety

The generated client is generic over auth capability:

type ClientAuth = 'browser' | 'session' | 'devKey' | 'impersonation';
type ServerAuth = 'apiKey' | 'jwt' | 'cookie';
type Auth = ClientAuth | ServerAuth;

Generated services use those capabilities directly:

• Client/browser-only services require Client<ClientAuth>.
• Server-only services require Client<ServerAuth>.
• Mixed services preserve the existing new Service(client) syntax while omitting methods that are not valid for the provided client auth tier.
• Service .client internals are hidden from the public service type.
• Realtime accepts browser-capable clients in the Web SDK.

Examples:

const browserClient = Client.fromBrowser({ endpoint, projectId });
const serverClient = Client.fromAPIKey({ endpoint, projectId, apiKey });

new TablesDB(browserClient).createBooleanColumn; // Type error
new TablesDB(serverClient).createBooleanColumn;  // OK

new Functions(browserClient).delete; // Type error
new Functions(serverClient).delete;  // OK

Factory-created clients also hide internal helpers such as withJWT, withForwardedUserAgent, CHUNK_SIZE, and flatten. JavaScript function properties such as apply and arguments remain inherent to the constructable Client value.

Factory parameter types are wrapped with Prettify<T> so IDE hover displays the expanded object shape instead of opaque aliases.

Implementation Details

File	Change
templates/web/src/client.ts.twig	Generates one generic Client, static from* factories, hidden public factory surfaces, deprecated legacy setters, and spec-driven base factory params.
src/SDK/Language/Web.php	Provides Web-specific filters for service auth typing, base client params, and setter return types. Removes the old webClientHeaders spec workaround.
templates/web/src/services/template.ts.twig	Preserves new Service(client) syntax while hiding invalid methods and service .client from public types.
templates/web/src/services/realtime.ts.twig	Narrows Realtime to browser-capable Web clients.
templates/web/src/index.ts.twig	Re-exports the Web client auth capability types.
example.php	Cleans generated examples before regeneration to avoid stale files from previous platform renders.

Compatibility Notes

• new Client().setEndpoint(...).setProject(...).setKey(...) still works.
• Legacy setters are deprecated to guide new code toward static factories.
• Legacy setters are intentionally not visible on Client.fromBrowser(...), Client.fromAPIKey(...), or other factory-created clients.
• Internal with* helpers are not visible on either factory-created clients or legacy new Client() results.
• Old standalone server-client output has been removed in favor of the unified generic Web Client.

Validation

Recent validation performed on this branch:

• php example.php web server
• php example.php web client
• php example.php web console
• TypeScript smoke tests for server/client/console generated Web outputs covering:
  • legacy setters still supported on new Client()
  • legacy setters hidden from factory clients
  • internal with* helpers hidden
  • static internals such as CHUNK_SIZE and flatten hidden
  • browser clients reject server-only methods such as Functions.delete and TablesDB.createBooleanColumn
  • server clients accept those server-only methods
  • service .client hidden from public service types
  • client-platform output omits fromAPIKey and fromJWT
  • console-platform output accepts spec-driven mode and platform params
• tsc on final generated examples/web/src/client.ts
• composer lint-twig
• php -l src/SDK/Language/Web.php
• git diff --check

[greptile-apps]

Greptile Summary

This PR unifies the Web SDK into a single generic ClientRuntime<TAuth> class with static auth factories (fromBrowser, fromSession, fromAPIKey, fromCookie, fromJWT, fromDevKey, fromImpersonation) and exposes it as a cast Client constructor. Service templates are updated to use Omit-based type aliases that enforce auth-tier constraints at compile time.

• ClientRuntime replaces the original Client class; the public Client surface is a ClientConstructor type cast that hides legacy setters and internal helpers from factory-created instances.
• template.ts.twig computes per-service auth flags via the new webServiceAuth PHP filter and generates Omit-based type aliases to restrict server-only or client-only methods on mixed-tier services.
• realtime.ts.twig is narrowed to accept Client<ClientAuth> for the Web SDK, and window/setInterval usages are guarded for Node.js compatibility.

Confidence Score: 4/5

The core factory and type-alias machinery works correctly; outstanding open threads around jwt/ClientAuth classification, setter copy-vs-mutate semantics, and fromCookie platform guard should be resolved before merging.

The new Omit-based auth-tier enforcement is functionally sound and the window/Node.js guards are a genuine improvement. However, unresolved threads from prior rounds — jwt placed in ServerAuth making it unusable in browser service constructors, setKey/setSession/setDevKey copy-returning semantics silently breaking the documented legacy imperative style, and fromCookie emitted unconditionally in server builds — represent real mismatches between the documented API and the generated output.

templates/web/src/client.ts.twig deserves the most attention for the jwt/ServerAuth placement, setter copy-vs-mutate behaviour, and unguarded fromCookie. src/SDK/Language/Web.php contains the unused webMethodThisGate helper that should be removed.

Important Files Changed

Filename	Overview
templates/web/src/client.ts.twig	Major refactor introducing generic ClientRuntime, static auth factories, and type aliases. Several previously noted issues around runtime/platform mutation, JWT classification, and missing guards remain open.
templates/web/src/services/template.ts.twig	Refactored to Omit-based type aliases for auth-tier enforcement; thisGate placeholder is always empty (dead code path), but functional correctness is preserved by the Omit approach.
src/SDK/Language/Web.php	Adds webServiceAuth, webClientBaseParams, webClientSetterReturnType helpers and Twig filters; webMethodThisGate is registered but unused.
templates/web/src/services/realtime.ts.twig	Narrows Realtime constructor to Client for Web SDK and guards window/setInterval usage for Node.js compatibility.
templates/web/src/index.ts.twig	Re-exports new SDKPlatform, ClientAuth, ServerAuth types alongside existing exports; minor newline fix.
.github/workflows/sdk-build-validation.yml	Adds web/server to the CI matrix; web/client platform generation path remains untested in CI (noted in prior review).
tests/resources/spec.json	Adds Cookie, DevKey, and three Impersonate* global headers to support new factory methods in the test spec.

_{Reviews (30): Last reviewed commit: "Update web test auth headers fixture" | Re-trigger Greptile}

[ChiragAgg5k]

Superseded by #1511, which now consolidates the Web, Flutter, and Apple isomorphic SDK changes.