feat: Isomorphic SDKs

.github/workflows/sdk-build-validation.yml

@@ -38,6 +38,9 @@ jobs:
             platform: client
 
           # Server SDKs
+          - sdk: web
+            platform: server
+
           - sdk: node
             platform: server
 

src/SDK/Language/Apple.php

@@ -118,7 +118,7 @@ public function getFiles(): array
             [
                 'scope'         => 'default',
                 'destination'   => '/Sources/{{ spec.title | caseUcfirst}}/Services/Service.swift',
-                'template'      => 'swift/Sources/Service.swift.twig',
+                'template'      => 'apple/Sources/Service.swift.twig',
             ],
             [
                 'scope'         => 'default',

src/SDK/Language/Flutter.php

@@ -33,7 +33,7 @@ public function getFiles(): array
             [
                 'scope'         => 'default',
                 'destination'   => '/lib/src/service.dart',
-                'template'      => 'dart/lib/src/service.dart.twig',
+                'template'      => 'flutter/lib/src/service.dart.twig',
             ],
             [
                 'scope'         => 'default',

src/SDK/Language/Web.php

@@ -405,6 +405,10 @@ public function getReturn(array $method, array $spec): string
         }
 
         if ($method['type'] === 'location') {
+            $platforms = $method['platforms'] ?? [];
+            if ((in_array('server', $platforms, true) || in_array('console', $platforms, true)) && !in_array('client', $platforms, true)) {
+                return 'Promise<ArrayBuffer>';
+            }
             return 'string';
         }
 
@@ -481,6 +485,167 @@ public function getSubSchema(array $property, array $spec, string $methodName =
         return $this->getTypeName($property);
     }
 
+    /**
+     * Determine whether a method supports client-side platforms.
+     */
+    protected function methodSupportsClient(array $method): bool
+    {
+        return in_array('client', $method['platforms'] ?? [], true);
+    }
+
+    /**
+     * Determine whether a method supports server/console platforms.
+     */
+    protected function methodSupportsServer(array $method): bool
+    {
+        $platforms = $method['platforms'] ?? [];
+        return in_array('server', $platforms, true) || in_array('console', $platforms, true);
+    }
+
+    /**
+     * Compute auth-related flags for a Web service.
+     *
+     * @return array<string, mixed>
+     */
+    public function webServiceAuth(array $service): array
+    {
+        $hasClientTier = false;
+        $hasServerTier = false;
+        $hasServerOnly = false;
+        $hasClientOnly = false;
+        $hasUpload = false;
+        $needsServiceFlatten = false;
+        $serverOnlyMethods = [];
+        $clientOnlyMethods = [];
+
+        foreach ($service['methods'] ?? [] as $method) {
+            $hasClient = $this->methodSupportsClient($method);
+            $hasServer = $this->methodSupportsServer($method);
+            $methodName = $this->toCamelCase($method['name'] ?? '');
+
+            if ($hasClient) {
+                $hasClientTier = true;
+            }
+            if ($hasServer) {
+                $hasServerTier = true;
+            }
+            if ($hasServer && !$hasClient) {
+                $hasServerOnly = true;
+                $serverOnlyMethods[] = $methodName;
+            }
+            if ($hasClient && !$hasServer) {
+                $hasClientOnly = true;
+                $clientOnlyMethods[] = $methodName;
+            }
+            if (in_array('multipart/form-data', $method['consumes'] ?? [], true)) {
+                $hasUpload = true;
+            }
+            if (in_array($method['type'] ?? '', ['location', 'webAuth'], true)) {
+                $needsServiceFlatten = true;
+            }
+        }
+
+        $hasMixedTier = $hasClientTier && $hasServerTier;
+
+        return [
+            'hasClientTier'   => $hasClientTier,
+            'hasServerTier'   => $hasServerTier,
+            'hasMixedTier'    => $hasMixedTier,
+            'needsServerAuth' => $hasServerTier && (!$hasMixedTier || $hasServerOnly),
+            'needsClientAuth' => $hasClientTier && (!$hasMixedTier || $hasClientOnly),
+            'hasUpload'       => $hasUpload,
+            'needsServiceFlatten' => $needsServiceFlatten,
+            'serverOnlyMethods' => array_values(array_unique($serverOnlyMethods)),
+            'clientOnlyMethods' => array_values(array_unique($clientOnlyMethods)),
+        ];
+    }
+
+    /**
+     * Build the Web client config keys required by the isomorphic auth factories.
+     *
+     * @return string[]
+     */
+    public function webClientConfigKeys(array $headers): array
+    {
+        $keys = [];
+        foreach ($headers as $header) {
+            $keys[] = strtolower((string)($header['key'] ?? ''));
+        }
+
+        return array_values(array_unique(array_filter($keys)));
+    }
+
+    /**
+     * Build the TypeScript `this:` receiver constraint for a method in a Web service.
+     */
+    public function webMethodAuthReceiver(array $method, array $service): string
+    {
+        $auth = $this->webServiceAuth($service);
+        if (!$auth['hasMixedTier']) {
+            return '';
+        }
+
+        $serviceName = $this->toPascalCase($service['name'] ?? '');
+
+        if (!$this->methodSupportsClient($method)) {
+            return 'this: ' . $serviceName . '<ServerAuth>, ';
+        }
+        if (!$this->methodSupportsServer($method)) {
+            return 'this: ' . $serviceName . '<ClientAuth>, ';
+        }
+
+        return '';
+    }
+
+    public function webClientBaseParams(array $headers): array
+    {
+        $params = [
+            'Project' => [
+                'name' => 'projectId',
+                'required' => true,
+                'setter' => 'setProject',
+            ],
+            'Locale' => [
+                'name' => 'locale',
+                'required' => false,
+                'setter' => 'setLocale',
+            ],
+            'Mode' => [
+                'name' => 'mode',
+                'required' => false,
+                'setter' => 'setMode',
+            ],
+            'Platform' => [
+                'name' => 'platform',
+                'required' => false,
+                'setter' => 'setPlatform',
+            ],
+        ];
+
+        $baseParams = [];
+        foreach ($headers as $header) {
+            $key = $header['key'] ?? '';
+            if (isset($params[$key])) {
+                $baseParams[] = $params[$key];
+            }
+        }
+
+        return $baseParams;
+    }
+
+    public function webClientSetterReturnType(array $header): string
+    {
+        return match ($header['key'] ?? '') {
+            'Key' => "ClientRuntime<'apiKey'>",
+            'Cookie' => "ClientRuntime<'cookie'>",
+            'JWT' => "ClientRuntime<'jwt'>",
+            'Session' => "ClientRuntime<'session'>",
+            'DevKey' => "ClientRuntime<'devKey'>",
+            'ImpersonateUserId', 'ImpersonateUserEmail', 'ImpersonateUserPhone' => "ClientRuntime<'impersonation'>",
+            default => 'this',
+        };
+    }
+
     public function getFilters(): array
     {
         return \array_merge(parent::getFilters(), [
@@ -541,6 +706,21 @@ public function getFilters(): array
 
                 return $condition;
             }, ['is_safe' => ['html']]),
+            new TwigFilter('webServiceAuth', function (array $service) {
+                return $this->webServiceAuth($service);
+            }),
+            new TwigFilter('webMethodAuthReceiver', function (array $method, array $service) {
+                return $this->webMethodAuthReceiver($method, $service);
+            }, ['is_safe' => ['html']]),
+            new TwigFilter('webClientBaseParams', function (array $headers) {
+                return $this->webClientBaseParams($headers);
+            }),
+            new TwigFilter('webClientConfigKeys', function (array $headers) {
+                return $this->webClientConfigKeys($headers);
+            }),
+            new TwigFilter('webClientSetterReturnType', function (array $header) {
+                return $this->webClientSetterReturnType($header);
+            }, ['is_safe' => ['html']]),
             new TwigFilter('comment2', function ($value) {
                 $value = explode("\n", $value);
                 foreach ($value as $key => $line) {

templates/android/docs/java/example.md.twig

@@ -19,15 +19,37 @@ import {{ sdk.namespace | caseDot }}.enums.{{ parameter.enumName | caseUcfirst }
 {% endif %}
 {% endfor %}
 
-Client client = new Client(context)
-    {%~ if method.auth|length > 0 %}
-    .setEndpoint("{{ spec.endpointDocs | raw }}") // Your API Endpoint
-    {%~ for node in method.auth %}
-    {%~ for key,header in node|keys %}
-    .set{{header | caseUcfirst}}("{{node[header]['x-appwrite']['demo'] | raw }}"){% if loop.last %};{% endif %} // {{ node[header].description }}
-    {%~ endfor %}
-    {%~ endfor %}
-    {%~ endif %}
+{% set authNode = {} %}
+{% for node in method.auth %}
+{% set authNode = authNode|merge(node) %}
+{% endfor %}
+{% set authHeaders = [] %}
+{% for header in authNode|keys %}
+{% if not (header == 'Session' and 'client' in method.platforms) %}
+{% set authHeaders = authHeaders|merge([header]) %}
+{% endif %}
+{% endfor %}
+{% set factory = 'from' %}
+{% if 'ImpersonateUserId' in authHeaders or 'ImpersonateUserEmail' in authHeaders or 'ImpersonateUserPhone' in authHeaders %}{% set factory = 'fromImpersonation' %}{% elseif 'DevKey' in authHeaders %}{% set factory = 'fromDevKey' %}{% elseif 'Session' in authHeaders %}{% set factory = 'fromSession' %}{% endif %}
+{% if method.auth|length > 0 %}
+Client client = Client.{{ factory }}(
+    context,
+    "{{ authNode.Project['x-appwrite']['demo'] | raw }}", // Your project ID
+{% if factory == 'fromSession' or factory == 'fromImpersonation' %}
+    "{{ authNode.Session['x-appwrite']['demo'] | raw }}", // {{ authNode.Session.description }}
+{% elseif factory == 'fromDevKey' %}
+    "{{ authNode.DevKey['x-appwrite']['demo'] | raw }}", // {{ authNode.DevKey.description }}
+{% endif %}
+{% if factory == 'fromImpersonation' %}
+    {% if 'ImpersonateUserId' in authHeaders %}"{{ authNode.ImpersonateUserId['x-appwrite']['demo'] | raw }}", // {{ authNode.ImpersonateUserId.description }}{% else %}null,{% endif %}
+    {% if 'ImpersonateUserEmail' in authHeaders %}"{{ authNode.ImpersonateUserEmail['x-appwrite']['demo'] | raw }}", // {{ authNode.ImpersonateUserEmail.description }}{% else %}null,{% endif %}
+    {% if 'ImpersonateUserPhone' in authHeaders %}"{{ authNode.ImpersonateUserPhone['x-appwrite']['demo'] | raw }}", // {{ authNode.ImpersonateUserPhone.description }}{% else %}null,{% endif %}
+{% endif %}
+    "{{ spec.endpointDocs | raw }}" // Your API Endpoint
+);
+{% else %}
+Client client = new Client(context);
+{% endif %}
 
 {{ service.name | caseUcfirst }} {{ service.name | caseCamel }} = new {{ service.name | caseUcfirst }}(client);
 
@@ -56,6 +78,5 @@ Client client = new Client(context)
     })
 );
 {% endif %}
-
 {% endfor %}
 ```

templates/android/docs/kotlin/example.md.twig

@@ -19,15 +19,32 @@ import {{ sdk.namespace | caseDot }}.Permission
 import {{ sdk.namespace | caseDot }}.Role
 {% endif %}
 
+{% set authNode = {} %}
+{% for node in method.auth %}
+{% set authNode = authNode|merge(node) %}
+{% endfor %}
+{% set authHeaders = [] %}
+{% for header in authNode|keys %}
+{% if not (header == 'Session' and 'client' in method.platforms) %}
+{% set authHeaders = authHeaders|merge([header]) %}
+{% endif %}
+{% endfor %}
+{% set factory = 'from' %}
+{% if 'ImpersonateUserId' in authHeaders or 'ImpersonateUserEmail' in authHeaders or 'ImpersonateUserPhone' in authHeaders %}{% set factory = 'fromImpersonation' %}{% elseif 'DevKey' in authHeaders %}{% set factory = 'fromDevKey' %}{% elseif 'Session' in authHeaders %}{% set factory = 'fromSession' %}{% endif %}
+{% if method.auth|length > 0 %}
+val client = Client.{{ factory }}(
+    context = context,
+    endpoint = "{{ spec.endpointDocs | raw }}", // Your API Endpoint
+    projectId = "{{ authNode.Project['x-appwrite']['demo'] | raw }}"{% if authHeaders|length > 1 %},{% endif %} // Your project ID
+{% for header in authHeaders %}
+{% if header != 'Project' %}
+    {% if header == 'Session' %}session{% elseif header == 'DevKey' %}devKey{% elseif header == 'ImpersonateUserId' %}userId{% elseif header == 'ImpersonateUserEmail' %}userEmail{% elseif header == 'ImpersonateUserPhone' %}userPhone{% else %}{{ header | caseCamel }}{% endif %} = "{{ authNode[header]['x-appwrite']['demo'] | raw }}"{% if not loop.last %},{% endif %} // {{ authNode[header].description }}
+{% endif %}
+{% endfor %}
+)
+{% else %}
 val client = Client(context)
-    {%~ if method.auth|length > 0 %}
-    .setEndpoint("{{ spec.endpointDocs | raw }}") // Your API Endpoint
-    {%~ for node in method.auth %}
-    {%~ for key,header in node|keys %}
-    .set{{header | caseUcfirst}}("{{node[header]['x-appwrite']['demo'] | raw }}") // {{node[header].description}}
-    {%~ endfor %}
-    {%~ endfor %}
-    {%~ endif %}
+{% endif %}
 
 val {{ service.name | caseCamel }} = {{ service.name | caseUcfirst }}(client)