appwrite-utils-cli 1.7.8 → 1.7.9

package/dist/functions/templates/hono-typescript/src/app.ts

@@ -0,0 +1,180 @@
+import { Hono } from "hono";
+import { Client, Databases, Storage, Users } from "node-appwrite";
+import { appwriteMiddleware, requestLogger, errorHandler, appwriteHeaders } from "./middleware/appwrite.js";
+
+// Create the Hono app
+export const app = new Hono();
+
+// Global middleware - Applied to all routes
+app.use("*", errorHandler());
+app.use("*", requestLogger());
+app.use("*", appwriteHeaders());
+
+// Helper function to get initialized Appwrite client
+function getAppwriteClient(c: any) {
+  const appwriteContext = c.get("appwriteContext");
+
+  const client = new Client()
+    .setEndpoint(process.env["APPWRITE_FUNCTION_ENDPOINT"]!)
+    .setProject(process.env["APPWRITE_FUNCTION_PROJECT_ID"]!)
+    .setKey(appwriteContext.req.headers["x-appwrite-key"] || process.env["APPWRITE_FUNCTION_API_KEY"]!);
+
+  return {
+    client,
+    databases: new Databases(client),
+    storage: new Storage(client),
+    users: new Users(client),
+  };
+}
+
+// Routes
+
+// Health check endpoint
+app.get("/", (c) => {
+  c.log("Health check requested");
+  return c.json({
+    message: "Hello from {{functionName}} with Hono!",
+    functionName: "{{functionName}}",
+    timestamp: new Date().toISOString(),
+    method: c.req.method,
+    path: c.req.path,
+    appwriteTrigger: c.appwrite.trigger,
+    isAuthenticated: c.appwrite.isUserAuthenticated(),
+  });
+});
+
+// API health endpoint
+app.get("/health", (c) => {
+  return c.json({
+    status: "healthy",
+    timestamp: new Date().toISOString(),
+    version: "1.0.0",
+    environment: {
+      nodeVersion: process.version,
+      appwriteEndpoint: process.env["APPWRITE_FUNCTION_ENDPOINT"],
+      appwriteProject: process.env["APPWRITE_FUNCTION_PROJECT_ID"],
+      appwriteRuntime: process.env["APPWRITE_FUNCTION_RUNTIME_NAME"],
+    },
+  });
+});
+
+// Example API endpoints
+
+// GET /api/user - Get current user info
+app.get("/api/user", async (c) => {
+  if (!c.appwrite.isUserAuthenticated()) {
+    return c.json({ error: "User not authenticated" }, 401);
+  }
+
+  try {
+    const { users } = getAppwriteClient(c);
+    const user = await users.get(c.appwrite.userId!);
+
+    c.log(`Retrieved user info for ${user.email}`);
+    return c.json({ user });
+  } catch (error) {
+    c.error(`Failed to get user: ${error}`);
+    return c.json({ error: "Failed to retrieve user" }, 500);
+  }
+});
+
+// POST /api/webhook - Generic webhook handler
+app.post("/api/webhook", async (c) => {
+  const data = await c.req.json();
+
+  c.log(`Webhook received: ${JSON.stringify(data)}`);
+
+  // Process webhook data here
+  // Example: Save to database, send notifications, etc.
+
+  return c.json({
+    message: "Webhook processed successfully",
+    received: data,
+    timestamp: new Date().toISOString(),
+    event: c.appwrite.event,
+  });
+});
+
+// GET /api/databases - List databases (requires API key)
+app.get("/api/databases", async (c) => {
+  if (!c.appwrite.isApiKeyRequest()) {
+    return c.json({ error: "API key required" }, 401);
+  }
+
+  try {
+    const { databases } = getAppwriteClient(c);
+    const databasesList = await databases.list();
+
+    c.log(`Listed ${databasesList.databases.length} databases`);
+    return c.json({ databases: databasesList.databases });
+  } catch (error) {
+    c.error(`Failed to list databases: ${error}`);
+    return c.json({ error: "Failed to list databases" }, 500);
+  }
+});
+
+// POST /api/data/:databaseId/:collectionId - Create document
+app.post("/api/data/:databaseId/:collectionId", async (c) => {
+  const databaseId = c.req.param("databaseId");
+  const collectionId = c.req.param("collectionId");
+  const data = await c.req.json();
+
+  try {
+    const { databases } = getAppwriteClient(c);
+    const document = await databases.createDocument(
+      databaseId,
+      collectionId,
+      "unique()",
+      data
+    );
+
+    c.log(`Created document in ${databaseId}/${collectionId}`);
+    return c.json({ document }, 201);
+  } catch (error) {
+    c.error(`Failed to create document: ${error}`);
+    return c.json({ error: "Failed to create document" }, 500);
+  }
+});
+
+// GET /api/data/:databaseId/:collectionId - List documents
+app.get("/api/data/:databaseId/:collectionId", async (c) => {
+  const databaseId = c.req.param("databaseId");
+  const collectionId = c.req.param("collectionId");
+  const limit = parseInt(c.req.query("limit") || "25");
+  const offset = parseInt(c.req.query("offset") || "0");
+
+  try {
+    const { databases } = getAppwriteClient(c);
+    const documents = await databases.listDocuments(
+      databaseId,
+      collectionId,
+      undefined,
+      limit,
+      offset
+    );
+
+    c.log(`Listed ${documents.documents.length} documents from ${databaseId}/${collectionId}`);
+    return c.json({ documents: documents.documents, total: documents.total });
+  } catch (error) {
+    c.error(`Failed to list documents: ${error}`);
+    return c.json({ error: "Failed to list documents" }, 500);
+  }
+});
+
+// Handle 404s
+app.notFound((c) => {
+  c.log(`Route not found: ${c.req.method} ${c.req.path}`);
+  return c.json({
+    error: "Not Found",
+    message: `Route ${c.req.method} ${c.req.path} not found`,
+    availableRoutes: [
+      "GET /",
+      "GET /health",
+      "GET /api/user",
+      "POST /api/webhook",
+      "GET /api/databases",
+      "POST /api/data/:databaseId/:collectionId",
+      "GET /api/data/:databaseId/:collectionId",
+    ],
+  }, 404);
+});

package/dist/functions/templates/hono-typescript/src/context.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+
+/**
+ * Appwrite Request Headers Schema
+ */
+export const AppwriteHeadersSchema = z.object({
+    "x-appwrite-trigger": z.enum(["http", "schedule", "event"]).optional(),
+    "x-appwrite-event": z.string().optional(),
+    "x-appwrite-key": z.string().optional(),
+    "x-appwrite-user-id": z.string().optional(),
+    "x-appwrite-user-jwt": z.string().optional(),
+    "x-appwrite-country-code": z.string().optional(),
+    "x-appwrite-continent-code": z.string().optional(),
+    "x-appwrite-continent-eu": z.string().optional(),
+}).catchall(z.string()); // Allow additional headers
+
+/**
+ * Appwrite Environment Variables Schema
+ */
+export const AppwriteEnvSchema = z.object({
+    APPWRITE_FUNCTION_API_ENDPOINT: z.string(),
+    APPWRITE_VERSION: z.string(),
+    APPWRITE_REGION: z.string(),
+    APPWRITE_FUNCTION_API_KEY: z.string().optional(),
+    APPWRITE_FUNCTION_ID: z.string(),
+    APPWRITE_FUNCTION_NAME: z.string(),
+    APPWRITE_FUNCTION_DEPLOYMENT: z.string(),
+    APPWRITE_FUNCTION_PROJECT_ID: z.string(),
+    APPWRITE_FUNCTION_RUNTIME_NAME: z.string(),
+    APPWRITE_FUNCTION_RUNTIME_VERSION: z.string(),
+});
+
+/**
+ * Appwrite Request Schema (full version from docs)
+ */
+export const AppwriteRequestSchema = z.object({
+    bodyText: z.string().optional(),
+    bodyJson: z.union([z.any(), z.string()]).transform((t) => {
+        if (typeof t === "string") {
+            try {
+                return JSON.parse(t);
+            } catch {
+                return null;
+            }
+        }
+        return t;
+    }).optional(),
+    body: z.any().optional(),
+    headers: AppwriteHeadersSchema,
+    scheme: z.enum(["http", "https"]).optional(),
+    method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"]),
+    url: z.string().optional(),
+    host: z.string().optional(),
+    port: z.number().or(z.string()).optional(),
+    path: z.string().optional(),
+    queryString: z.string().optional(),
+    query: z.record(z.string(), z.any()).optional(),
+    variables: z.record(z.string(), z.any()).optional(),
+    text: z.any().optional(),
+    payload: z.string().optional(),
+});
+
+/**
+ * Appwrite Response Schema
+ */
+export const AppwriteResponseSchema = z.object({
+    json: z.any(),
+    text: z.any(),
+    empty: z.any().optional(),
+    binary: z.any().optional(),
+    redirect: z.any().optional(),
+});
+
+/**
+ * Log Function Schema - Simple function type
+ */
+export const AppwriteLogSchema = z.any();
+
+/**
+ * Error Function Schema - Simple function type
+ */
+export const AppwriteErrorSchema = z.any();
+
+/**
+ * Complete Appwrite Context Schema
+ */
+export const AppwriteContextSchema = z.object({
+    req: AppwriteRequestSchema,
+    res: AppwriteResponseSchema,
+    log: AppwriteLogSchema,
+    error: AppwriteErrorSchema,
+});
+
+/**
+ * Type inference helpers
+ */
+export type AppwriteHeaders = z.infer<typeof AppwriteHeadersSchema>;
+export type AppwriteEnv = z.infer<typeof AppwriteEnvSchema>;
+export type AppwriteRequest = z.infer<typeof AppwriteRequestSchema>;
+export type AppwriteResponse = z.infer<typeof AppwriteResponseSchema>;
+export type AppwriteLog = z.infer<typeof AppwriteLogSchema>;
+export type AppwriteError = z.infer<typeof AppwriteErrorSchema>;
+export type AppwriteContext = z.infer<typeof AppwriteContextSchema>;

package/dist/functions/templates/hono-typescript/src/index.ts

@@ -0,0 +1,54 @@
+import { app } from "./app.js";
+import { AppwriteContext, AppwriteContextSchema } from "./context.js";
+import { convertAppwriteToWebRequest } from "./adapters/request.js";
+import { convertWebResponseToAppwrite } from "./adapters/response.js";
+import { appwriteMiddleware } from "./middleware/appwrite.js";
+
+/**
+ * Main Appwrite function entry point
+ * This function receives the Appwrite context and routes it through Hono
+ */
+export default async function (context: AppwriteContext) {
+  const { req, res, log, error } = context;
+
+  try {
+    // Optional: Validate the context using Zod schema
+    AppwriteContextSchema.parse(context);
+    log("Context validation successful");
+
+    // Add Appwrite context middleware to the Hono app
+    app.use("*", appwriteMiddleware(context));
+
+    // Convert Appwrite request to Web API Request for Hono
+    const webRequest = convertAppwriteToWebRequest(req);
+
+    log(`Processing ${req.method} request to ${req.path || "/"}`);
+
+    // Create execution environment for Hono
+    const env = {
+      // Add any environment variables or context needed by Hono
+      APPWRITE_FUNCTION_ENDPOINT: process.env["APPWRITE_FUNCTION_ENDPOINT"],
+      APPWRITE_FUNCTION_PROJECT_ID: process.env["APPWRITE_FUNCTION_PROJECT_ID"],
+      APPWRITE_FUNCTION_API_KEY: process.env["APPWRITE_FUNCTION_API_KEY"],
+    };
+
+    // Process request through Hono app
+    const honoResponse = await app.fetch(webRequest, env);
+
+    // Convert Hono response back to Appwrite response format
+    await convertWebResponseToAppwrite(honoResponse, res);
+
+    log(`Request completed with status ${honoResponse.status}`);
+
+  } catch (validationError) {
+    error(`Function execution failed: ${validationError}`);
+
+    // Return error response
+    return res.json({
+      error: "Function execution failed",
+      message: validationError instanceof Error ? validationError.message : String(validationError),
+      functionName: "{{functionName}}",
+      timestamp: new Date().toISOString(),
+    }, 500);
+  }
+}

package/dist/functions/templates/hono-typescript/src/middleware/appwrite.ts

@@ -0,0 +1,119 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppwriteContext } from "../context.js";
+
+// Extend Hono's context to include Appwrite context
+declare module "hono" {
+  interface ContextVariableMap {
+    appwriteContext: AppwriteContext;
+  }
+}
+
+/**
+ * Middleware to inject Appwrite context into Hono
+ */
+export const appwriteMiddleware = (appwriteContext: AppwriteContext): MiddlewareHandler => {
+  return async (c, next) => {
+    // Inject Appwrite context into Hono context
+    c.set("appwriteContext", appwriteContext);
+
+    // Add logging helper methods to Hono context
+    c.log = (message: string) => {
+      appwriteContext.log(`[${c.req.method} ${c.req.path}] ${message}`);
+    };
+
+    c.error = (message: string) => {
+      appwriteContext.error(`[${c.req.method} ${c.req.path}] ${message}`);
+    };
+
+    await next();
+  };
+};
+
+/**
+ * Middleware for request logging
+ */
+export const requestLogger = (): MiddlewareHandler => {
+  return async (c, next) => {
+    const start = Date.now();
+    const appwriteContext = c.get("appwriteContext");
+
+    appwriteContext?.log(`→ ${c.req.method} ${c.req.path}`);
+
+    await next();
+
+    const duration = Date.now() - start;
+    appwriteContext?.log(`← ${c.req.method} ${c.req.path} ${c.res.status} (${duration}ms)`);
+  };
+};
+
+/**
+ * Middleware for error handling
+ */
+export const errorHandler = (): MiddlewareHandler => {
+  return async (c, next) => {
+    try {
+      await next();
+    } catch (err) {
+      const appwriteContext = c.get("appwriteContext");
+      const error = err instanceof Error ? err : new Error(String(err));
+
+      appwriteContext?.error(`Error in ${c.req.method} ${c.req.path}: ${error.message}`);
+
+      return c.json(
+        {
+          error: "Internal Server Error",
+          message: error.message,
+          path: c.req.path,
+          method: c.req.method,
+        },
+        500
+      );
+    }
+  };
+};
+
+/**
+ * Middleware to extract and validate Appwrite headers
+ */
+export const appwriteHeaders = (): MiddlewareHandler => {
+  return async (c, next) => {
+    const appwriteContext = c.get("appwriteContext");
+    const headers = appwriteContext?.req.headers;
+
+    // Add helpful getters for common Appwrite headers
+    c.appwrite = {
+      trigger: headers?.["x-appwrite-trigger"] as "http" | "schedule" | "event" | undefined,
+      event: headers?.["x-appwrite-event"],
+      key: headers?.["x-appwrite-key"],
+      userId: headers?.["x-appwrite-user-id"],
+      userJwt: headers?.["x-appwrite-user-jwt"],
+      countryCode: headers?.["x-appwrite-country-code"],
+      continentCode: headers?.["x-appwrite-continent-code"],
+      continentEu: headers?.["x-appwrite-continent-eu"],
+      isUserAuthenticated: () => !!headers?.["x-appwrite-user-id"],
+      isApiKeyRequest: () => !!headers?.["x-appwrite-key"],
+    };
+
+    await next();
+  };
+};
+
+// Extend Hono context to include Appwrite helpers
+declare module "hono" {
+  interface Context {
+    log: (message: string) => void;
+    error: (message: string) => void;
+    appwrite: {
+      trigger?: "http" | "schedule" | "event";
+      event?: string;
+      key?: string;
+      userId?: string;
+      userJwt?: string;
+      countryCode?: string;
+      continentCode?: string;
+      continentEu?: string;
+      isUserAuthenticated: () => boolean;
+      isApiKeyRequest: () => boolean;
+    };
+  }
+}

package/dist/functions/templates/hono-typescript/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/functions/templates/typescript-node/README.md

@@ -0,0 +1,32 @@
+# TypeScript Node.js Function Template
+
+This is a TypeScript template for Appwrite Functions using Node.js runtime.
+
+## Structure
+- `src/index.ts`: Main function entry point
+- `src/appwriteRequest.ts`: Type definitions for Appwrite request object
+- `src/appwriteResponse.ts`: Type definitions for Appwrite response object
+
+## Usage
+Your function will receive:
+- `req`: AppwriteRequest object containing request data, headers, and environment variables
+- `res`: AppwriteResponse object for sending responses
+- `log`: Function for logging (shows in your function logs)
+- `error`: Function for error logging
+
+## Example Request
+```json
+{
+  "databaseId": "your-database-id",
+  "collectionId": "your-collection-id"
+}
+```
+
+## Development
+1. Install dependencies: `npm|yarn|bun install`
+2. Build: `npm|yarn|bun run build`
+3. Deploy: Function will be built automatically during deployment
+
+## Deployment
+Make sure it's inside `appwriteConfig.ts` functions array, and if you want to build it FIRST, before Appwrite (using your system), you can
+add the `predeployCommands` to the function in `appwriteConfig.ts` -- for an example, see `count-docs-in-collection` function.

package/dist/functions/templates/typescript-node/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{functionName}}",
+  "version": "1.0.0",
+  "description": "Appwrite TypeScript Node.js function",
+  "main": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "node-appwrite": "^13.0.0",
+    "appwrite-utils": "latest",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/dist/functions/templates/typescript-node/src/context.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+
+/**
+ * Appwrite Request Headers Schema
+ */
+export const AppwriteHeadersSchema = z.object({
+    "x-appwrite-trigger": z.enum(["http", "schedule", "event"]).optional(),
+    "x-appwrite-event": z.string().optional(),
+    "x-appwrite-key": z.string().optional(),
+    "x-appwrite-user-id": z.string().optional(),
+    "x-appwrite-user-jwt": z.string().optional(),
+    "x-appwrite-country-code": z.string().optional(),
+    "x-appwrite-continent-code": z.string().optional(),
+    "x-appwrite-continent-eu": z.string().optional(),
+}).catchall(z.string()); // Allow additional headers
+
+/**
+ * Appwrite Environment Variables Schema
+ */
+export const AppwriteEnvSchema = z.object({
+    APPWRITE_FUNCTION_API_ENDPOINT: z.string(),
+    APPWRITE_VERSION: z.string(),
+    APPWRITE_REGION: z.string(),
+    APPWRITE_FUNCTION_API_KEY: z.string().optional(),
+    APPWRITE_FUNCTION_ID: z.string(),
+    APPWRITE_FUNCTION_NAME: z.string(),
+    APPWRITE_FUNCTION_DEPLOYMENT: z.string(),
+    APPWRITE_FUNCTION_PROJECT_ID: z.string(),
+    APPWRITE_FUNCTION_RUNTIME_NAME: z.string(),
+    APPWRITE_FUNCTION_RUNTIME_VERSION: z.string(),
+});
+
+/**
+ * Appwrite Request Schema (full version from docs)
+ */
+export const AppwriteRequestSchema = z.object({
+    bodyText: z.string().optional(),
+    bodyJson: z.union([z.any(), z.string()]).transform((t) => {
+        if (typeof t === "string") {
+            try {
+                return JSON.parse(t);
+            } catch {
+                return null;
+            }
+        }
+        return t;
+    }).optional(),
+    body: z.any().optional(),
+    headers: AppwriteHeadersSchema,
+    scheme: z.enum(["http", "https"]).optional(),
+    method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"]),
+    url: z.string().optional(),
+    host: z.string().optional(),
+    port: z.number().or(z.string()).optional(),
+    path: z.string().optional(),
+    queryString: z.string().optional(),
+    query: z.record(z.string(), z.any()).optional(),
+    variables: z.record(z.string(), z.any()).optional(),
+    text: z.any().optional(),
+    payload: z.string().optional(),
+});
+
+/**
+ * Appwrite Response Schema
+ */
+export const AppwriteResponseSchema = z.object({
+    json: z.any(),
+    text: z.any(),
+    empty: z.any().optional(),
+    binary: z.any().optional(),
+    redirect: z.any().optional(),
+});
+
+/**
+ * Log Function Schema - Simple function type
+ */
+export const AppwriteLogSchema = z.any();
+
+/**
+ * Error Function Schema - Simple function type
+ */
+export const AppwriteErrorSchema = z.any();
+
+/**
+ * Complete Appwrite Context Schema
+ */
+export const AppwriteContextSchema = z.object({
+    req: AppwriteRequestSchema,
+    res: AppwriteResponseSchema,
+    log: AppwriteLogSchema,
+    error: AppwriteErrorSchema,
+});
+
+/**
+ * Type inference helpers
+ */
+export type AppwriteHeaders = z.infer<typeof AppwriteHeadersSchema>;
+export type AppwriteEnv = z.infer<typeof AppwriteEnvSchema>;
+export type AppwriteRequest = z.infer<typeof AppwriteRequestSchema>;
+export type AppwriteResponse = z.infer<typeof AppwriteResponseSchema>;
+export type AppwriteLog = z.infer<typeof AppwriteLogSchema>;
+export type AppwriteError = z.infer<typeof AppwriteErrorSchema>;
+export type AppwriteContext = z.infer<typeof AppwriteContextSchema>;

package/dist/functions/templates/typescript-node/src/index.ts

@@ -0,0 +1,29 @@
+import { Client } from "node-appwrite";
+import { AppwriteContext, AppwriteContextSchema } from "./context.js";
+
+export default async function (context: AppwriteContext) {
+  const { req, res, log, error } = context;
+
+  // Optional: Validate the context using Zod schema
+  try {
+    AppwriteContextSchema.parse(context);
+    log("Context validation successful");
+  } catch (validationError) {
+    error(`Context validation failed: ${validationError}`);
+  }
+
+  const client = new Client()
+    .setEndpoint(process.env["APPWRITE_FUNCTION_ENDPOINT"]!)
+    .setProject(process.env["APPWRITE_FUNCTION_PROJECT_ID"]!)
+    .setKey(req.headers["x-appwrite-key"] || "");
+
+  log(`Processing ${req.method} request to ${req.path}`);
+
+  return res.json({
+    message: "Hello from TypeScript function!",
+    functionName: "{{functionName}}",
+    method: req.method,
+    path: req.path,
+    headers: req.headers,
+  });
+}