feat(references): consume standards-based spec metadata and expose new services

package.json

@@ -32,7 +32,7 @@
         "@statsig/session-replay": "^3.33.0",
         "@statsig/statsig-node-core": "^0.19.3",
         "@statsig/web-analytics": "^3.33.0",
-        "@appwrite.io/specs": "github:appwrite/specs#9f7af415c733583dc4b32b090df0c89986407cbd",
+        "@appwrite.io/specs": "github:appwrite/specs#ad50888d2aaac4b027a8a733ddcef4543e90dea1",
         "h3": "^1.15.4",
         "sharp": "^0.34.5"
     },

src/lib/server/model-markdown.ts

@@ -1,3 +1,4 @@
+import { resolveVersion } from '$lib/utils/references';
 import {
     getApi,
     getSchema,
@@ -16,7 +17,7 @@ export async function generateModelMarkdown(
     modelName: string
 ): Promise<string | null> {
     try {
-        const version = versionParam === 'cloud' ? '1.8.x' : versionParam;
+        const version = resolveVersion(versionParam);
         const api = await getApi(version, 'console-web');
         const schema = getSchema(modelName, api);
 

src/lib/server/service-markdown.ts

@@ -1,3 +1,4 @@
+import { resolveVersion } from '$lib/utils/references';
 import { getService } from '../../routes/docs/references/[version]/[platform]/[service]/specs';
 import type { SDKMethod } from '../../routes/docs/references/[version]/[platform]/[service]/specs';
 
@@ -10,7 +11,7 @@ export async function generateServiceMarkdown(
     serviceName: string
 ): Promise<string | null> {
     try {
-        const version = versionParam === 'cloud' ? '1.8.x' : versionParam;
+        const version = resolveVersion(versionParam);
         const serviceData = await getService(version, platform, serviceName);
 
         const { service, methods } = serviceData;

src/lib/utils/references.ts

@@ -25,22 +25,39 @@ export const versions: Readonly<Array<Omit<Version, 'cloud'>>> = allVersions.fil
 
 export const latestVersion = allVersions[0];
 
+/**
+ * Resolves the public `cloud` alias to the newest versioned spec. Every
+ * consumer of spec data (service pages, model pages, markdown generators)
+ * must resolve through here so `cloud` always means the same version.
+ */
+export function resolveVersion(version: string): string {
+    return version === 'cloud' ? latestVersion : version;
+}
+
 export const Service = {
     Account: 'account',
+    Activities: 'activities',
+    Advisor: 'advisor',
+    Apps: 'apps',
     Avatars: 'avatars',
+    Backups: 'backups',
     Databases: 'databases',
     TablesDB: 'tablesDB',
     Functions: 'functions',
     Messaging: 'messaging',
     Health: 'health',
     Locale: 'locale',
+    OAuth2: 'oauth2',
+    Organization: 'organization',
     Presences: 'presences',
+    Proxy: 'proxy',
     Storage: 'storage',
     Teams: 'teams',
     Users: 'users',
     Sites: 'sites',
     Tokens: 'tokens',
-    Project: 'project'
+    Project: 'project',
+    Webhooks: 'webhooks'
 } as const;
 
 export type ServiceType = typeof Service;
@@ -71,7 +88,6 @@ export const Platform = {
     ServerRest: 'server-rest'
 } as const;
 
-type PlatformType = typeof Platform;
 export type Platform = (typeof Platform)[keyof typeof Platform];
 export const VALID_PLATFORMS = new Set(Object.values(Platform));
 
@@ -156,20 +172,28 @@ export const platformMap: Record<Language | string, string> = {
 
 export const serviceMap: Record<ServiceValue, string> = {
     [Service.Account]: 'Account',
+    [Service.Activities]: 'Activities',
+    [Service.Advisor]: 'Advisor',
+    [Service.Apps]: 'Apps',
     [Service.Avatars]: 'Avatars',
+    [Service.Backups]: 'Backups',
     [Service.Databases]: 'Databases',
     [Service.TablesDB]: 'TablesDB',
     [Service.Functions]: 'Functions',
     [Service.Messaging]: 'Messaging',
     [Service.Health]: 'Health',
     [Service.Locale]: 'Locale',
+    [Service.OAuth2]: 'OAuth2',
+    [Service.Organization]: 'Organization',
     [Service.Presences]: 'Presences',
+    [Service.Proxy]: 'Proxy',
     [Service.Storage]: 'Storage',
     [Service.Teams]: 'Teams',
     [Service.Users]: 'Users',
     [Service.Sites]: 'Sites',
     [Service.Tokens]: 'Tokens',
-    [Service.Project]: 'Project'
+    [Service.Project]: 'Project',
+    [Service.Webhooks]: 'Webhooks'
 };
 
 export const preferredVersion = writable<Version | null>(

src/routes/docs/references/[version]/[platform]/[service]/(components)/RateLimits.svelte

@@ -84,7 +84,7 @@
                     </thead>
                     <tbody class="web-table-body">
                         {#if hasMultipleKeys(rateKeys)}
-                            {#each rateKeys as key, i}
+                            {#each rateKeys as key (key)}
                                 <tr class="web-table-row">
                                     <td class="web-table-col"
                                         >{Math.floor(rateTime / 60)} minutes</td

src/routes/docs/references/[version]/[platform]/[service]/+page.server.ts

@@ -1,34 +1,43 @@
 import {
-    latestVersion,
     Platform,
+    resolveVersion,
     Service,
     type ServiceValue,
     versions
 } from '$lib/utils/references';
-import { getService } from './specs';
+import { getApi, getAvailablePlatforms, getAvailableServices, getService } from './specs';
 import { error } from '@sveltejs/kit';
 import type { EntryGenerator, PageServerLoad } from './$types';
 
 const services = Object.values(Service);
 const platforms = Object.values(Platform);
 
-export const entries: EntryGenerator = () => {
-    return ['cloud', ...(versions as string[])].flatMap((version) => {
-        return platforms.flatMap((platform) => {
-            return services.map((service) => {
-                return { service, version, platform };
-            });
-        });
-    });
+export const entries: EntryGenerator = async () => {
+    const combos: Array<{ service: string; version: string; platform: string }> = [];
+    for (const version of ['cloud', ...(versions as string[])]) {
+        const resolved = resolveVersion(version);
+        for (const platform of getAvailablePlatforms(resolved)) {
+            const documented = getAvailableServices(await getApi(resolved, platform));
+            for (const service of services) {
+                if (documented.has(service)) {
+                    combos.push({ service, version, platform });
+                }
+            }
+        }
+    }
+    return combos;
 };
 
 export const load: PageServerLoad = async ({ params }) => {
     const { platform, service } = params;
-    const version = params.version === 'cloud' ? latestVersion : params.version;
+    const version = resolveVersion(params.version);
 
     if (!versions.includes(version)) error(404, 'Invalid version');
     if (!platforms.includes(platform as Platform)) error(404, 'Invalid platform');
     if (!services.includes(service as ServiceValue)) error(404, 'Invalid service');
 
-    return getService(version, platform, service);
+    return {
+        ...(await getService(version, platform, service)),
+        platforms: getAvailablePlatforms(version)
+    };
 };

src/routes/docs/references/[version]/[platform]/[service]/+page.svelte

@@ -192,6 +192,11 @@
 
     let platformBindingForSelect = $derived(page.params.platform as Platform);
     let platform = $derived(/**$preferredPlatform ?? */ page.params.platform as Platform);
+    // Platforms whose SDK exists for the current version, keeping the current
+    // one listed even when it was discontinued so the select stays coherent.
+    let availablePlatforms = $derived(
+        data.platforms.includes(platform) ? data.platforms : [platform, ...data.platforms]
+    );
     let platformType = $derived(platform.startsWith('client-') ? 'CLIENT' : 'SERVER');
     let serviceName = $derived(serviceMap[data.service?.name]);
     let title = $derived(serviceName + API_REFERENCE_TITLE_SUFFIX);
@@ -233,14 +238,14 @@
                             value={platformBindingForSelect}
                             on:change={selectPlatform}
                             options={[
-                                ...Object.values(Platform)
+                                ...availablePlatforms
                                     .filter((p) => p.startsWith('client-'))
                                     .map((p) => ({
                                         value: p,
                                         label: platformMap[p],
                                         group: 'Client'
                                     })),
-                                ...Object.values(Platform)
+                                ...availablePlatforms
                                     .filter((p) => p.startsWith('server-'))
                                     .map((p) => ({
                                         value: p,
@@ -298,7 +303,7 @@
                     </div>
                 {/if}
             </section>
-            {#each Object.entries(groupMethodsByGroup(data.methods)) as [group, methods]}
+            {#each Object.values(groupMethodsByGroup(data.methods)) as methods, groupIndex (groupIndex)}
                 {#each sortMethods(methods) as method (method.id)}
                     <section class="web-article-content-grid-6-4">
                         <div class="web-article-content-grid-6-4-column-1 flex flex-col gap-8">
@@ -339,14 +344,16 @@
                                         process
                                         withLineNumbers={false}
                                     />
-                                    <div class="mt-6">
-                                        <Fence
-                                            language={platform}
-                                            content={method.demo}
-                                            process
-                                            withLineNumbers={false}
-                                        />
-                                    </div>
+                                    {#if method.demo !== null}
+                                        <div class="mt-6">
+                                            <Fence
+                                                language={platform}
+                                                content={method.demo}
+                                                process
+                                                withLineNumbers={false}
+                                            />
+                                        </div>
+                                    {/if}
                                 </div>
                             </div>
                         </div>
@@ -387,15 +394,15 @@
                         </button>
                     </div>
                     <ul class="web-references-menu-list">
-                        {#each Object.entries(groupMethodsByGroup(data.methods)) as [group, methods]}
+                        {#each Object.entries(groupMethodsByGroup(data.methods)) as [group, methods] (group)}
                             <li class="web-references-menu-group">
                                 {#if group !== ''}
                                     <h6 class="text-eyebrow text-greyscale-500 mb-2 uppercase">
                                         {formatGroup(group)}
                                     </h6>
                                 {/if}
                                 <ul class="flex flex-col gap-2">
-                                    {#each sortMethods(methods) as method}
+                                    {#each sortMethods(methods) as method (method.id)}
                                         <li class="web-references-menu-item">
                                             <a
                                                 href={`#${method.id}`}

src/routes/docs/references/[version]/[platform]/[service]/descriptions/activities.md

@@ -0,0 +1,3 @@
+The Activities service allows you to list and inspect activity events in your project. Activity events form an audit trail of what happened in the project, when, and by whom.
+
+Use it to review recent changes, power audit views, or investigate unexpected behavior by drilling into an individual event.

src/routes/docs/references/[version]/[platform]/[service]/descriptions/advisor.md

@@ -0,0 +1,3 @@
+The Advisor service surfaces actionable reports about your project resources. Each report groups insights that highlight issues or improvement opportunities — for example security, performance, or configuration recommendations — with descriptors for one-click remediation in the Appwrite Console.
+
+You can list and inspect reports and their individual insights, and delete reports you have addressed.

src/routes/docs/references/[version]/[platform]/[service]/descriptions/apps.md

@@ -0,0 +1,3 @@
+The Apps service allows you to manage OAuth2 applications in your project — their keys, secrets, scopes, and installations. Apps are the counterpart to the [OAuth2 service](/docs/references/cloud/server-nodejs/oauth2): you register an application here, and users authorize it through the standard OAuth2 flows.
+
+Each application carries its own keys and secrets for authenticating token exchanges, and exposes the OAuth2 and installation scopes it may request. Installations track where an application has been authorized, and installation tokens let an installed application act within the granted scopes.

src/routes/docs/references/[version]/[platform]/[service]/descriptions/backups.md

@@ -0,0 +1,3 @@
+The Backups service allows you to manage backup policies, archives, and restorations for your project.
+
+Backup policies define what gets backed up and on what schedule and retention. Archives are the resulting point-in-time snapshots, which you can list, inspect, and delete. When you need to recover data, create a restoration from an archive and track its progress until it completes.

src/routes/docs/references/[version]/[platform]/[service]/descriptions/oauth2.md

@@ -0,0 +1,5 @@
+The OAuth2 service allows you to use your Appwrite project as a standards-based OAuth2 and OpenID Connect identity provider. Third-party apps can request access to your project's resources through the standard authorization code flow, device authorization flow, and pushed authorization requests (PAR).
+
+Users approve or reject authorization requests, and approved grants can be listed, inspected, and revoked at any time, giving you complete control over which apps hold access and for how long.
+
+The service issues and refreshes standards-compliant access tokens, and exposes endpoints to list the organizations and projects an authorized token can access.

src/routes/docs/references/[version]/[platform]/[service]/descriptions/organization.md

@@ -0,0 +1,3 @@
+The Organization service allows you to manage your organization and the resources that live at the organization level — projects, memberships, API keys, and installations.
+
+Use it to create and manage the organization's projects, invite and manage members, and issue organization-scoped API keys for automation that spans multiple projects. Installations connect the organization to external providers.

src/routes/docs/references/[version]/[platform]/[service]/descriptions/webhooks.md

@@ -0,0 +1,3 @@
+The Webhooks service allows you to manage your project's webhooks. Webhooks notify an HTTP endpoint you control whenever selected events happen in your project, letting you integrate Appwrite with external systems in real time.
+
+You can create, update, and delete webhooks, choose which events each one subscribes to, and rotate a webhook's secret key used to sign deliveries so your endpoint can verify their authenticity.