appwrite-utils-cli 1.5.2 → 1.6.0

package/src/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/src/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/src/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/src/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/src/functions/templates/typescript-node/package.json

@@ -11,7 +11,8 @@
   },
   "dependencies": {
     "node-appwrite": "^13.0.0",
-    "appwrite-utils": "latest"
+    "appwrite-utils": "latest",
+    "zod": "^3.22.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/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/src/functions/templates/typescript-node/src/index.ts

@@ -1,23 +1,29 @@
 import { Client } from "node-appwrite";
-import { AppwriteRequest, type AppwriteResponse } from "appwrite-utils";
+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}`);
+  }
 
-export default async function ({
-  req,
-  res,
-  log,
-  error,
-}: {
-  req: AppwriteRequest;
-  res: AppwriteResponse;
-  log: (message: string) => void;
-  error: (message: string) => void;
-}) {
   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,
   });
 }

package/src/functions/templates/uv/pyproject.toml

@@ -7,6 +7,7 @@ readme = "README.md"
 requires-python = ">=3.9"
 dependencies = [
     "appwrite>=7.0.1",
+    "pydantic>=2.0.0",
 ]
 
 [build-system]

package/src/functions/templates/uv/src/context.py

@@ -0,0 +1,125 @@
+from collections.abc import Callable
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel, Field
+
+
+class AppwriteHeaders(BaseModel):
+    """Appwrite request headers"""
+
+    x_appwrite_trigger: Literal["http", "schedule", "event"] | None = Field(
+        None, alias="x-appwrite-trigger"
+    )
+    x_appwrite_event: str | None = Field(None, alias="x-appwrite-event")
+    x_appwrite_key: str | None = Field(None, alias="x-appwrite-key")
+    x_appwrite_user_id: str | None = Field(None, alias="x-appwrite-user-id")
+    x_appwrite_user_jwt: str | None = Field(None, alias="x-appwrite-user-jwt")
+    x_appwrite_country_code: str | None = Field(None, alias="x-appwrite-country-code")
+    x_appwrite_continent_code: str | None = Field(
+        None, alias="x-appwrite-continent-code"
+    )
+    x_appwrite_continent_eu: str | None = Field(None, alias="x-appwrite-continent-eu")
+
+    # Allow additional headers
+    model_config = {"extra": "allow", "populate_by_name": True}
+
+
+class AppwriteEnv(BaseModel):
+    """Appwrite environment variables"""
+
+    APPWRITE_FUNCTION_API_ENDPOINT: str
+    APPWRITE_VERSION: str
+    APPWRITE_REGION: str
+    APPWRITE_FUNCTION_API_KEY: str | None = None
+    APPWRITE_FUNCTION_ID: str
+    APPWRITE_FUNCTION_NAME: str
+    APPWRITE_FUNCTION_DEPLOYMENT: str
+    APPWRITE_FUNCTION_PROJECT_ID: str
+    APPWRITE_FUNCTION_RUNTIME_NAME: str
+    APPWRITE_FUNCTION_RUNTIME_VERSION: str
+
+
+class AppwriteRequest(Protocol):
+    """Appwrite function request object with proper callable typing"""
+
+    bodyText: str | None
+    bodyJson: dict[str, Any] | str | None
+    body: Any
+    headers: dict[str, str]
+    scheme: Literal["http", "https"] | None
+    method: Literal["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"]
+    url: str | None
+    host: str | None
+    port: int | str | None
+    path: str | None
+    queryString: str | None
+    query: dict[str, str | list[str]] | None
+    variables: dict[str, str] | None
+    payload: str | None
+
+    async def text(self) -> str: ...
+
+
+class AppwriteResponse(Protocol):
+    """Appwrite function response object with proper callable typing"""
+
+    def json(
+        self,
+        data: Any,
+        status: int | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None: ...
+
+    def text(
+        self,
+        body: str,
+        status: int | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None: ...
+
+    def empty(self) -> None: ...
+
+    def binary(self, data: bytes) -> None: ...
+
+    def redirect(self, url: str, status: int | None = None) -> None: ...
+
+
+class AppwriteContext(Protocol):
+    """Complete Appwrite function context with proper typing"""
+
+    req: AppwriteRequest
+    res: AppwriteResponse
+
+    def log(self, message: str) -> None: ...
+
+    def error(self, message: str) -> None: ...
+
+
+# Alternative: BaseModel version for cases where you need Pydantic features
+# but want proper typing hints
+
+
+class AppwriteRequestModel(BaseModel):
+    """Pydantic model for request validation (if needed)"""
+
+    bodyText: str | None = None
+    bodyJson: dict[str, Any] | str | None = None
+    body: Any = None
+    headers: dict[str, str] = Field(default_factory=dict)
+    scheme: Literal["http", "https"] | None = None
+    method: Literal["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"]
+    url: str | None = None
+    host: str | None = None
+    port: int | str | None = None
+    path: str | None = None
+    queryString: str | None = None
+    query: dict[str, str | list[str]] | None = None
+    variables: dict[str, str] | None = None
+    payload: str | None = None
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+# Type alias for the log/error functions
+LogFunction = Callable[[str], None]
+ErrorFunction = Callable[[str], None]

package/src/functions/templates/uv/src/index.py

@@ -1,16 +1,46 @@
+import os
 from appwrite.client import Client
+from context import AppwriteContext, AppwriteHeaders, AppwriteRequestModel
 
-def main(context):
+def main(context: AppwriteContext):
     req = context.req
     res = context.res
     log = context.log
     error = context.error
 
+    # Optional: Validate request headers using Pydantic
+    try:
+        headers = AppwriteHeaders.model_validate(req.headers)
+        log("Headers validation successful")
+    except Exception as validation_error:
+        error(f"Headers validation failed: {validation_error}")
+
+    # Optional: Validate full request using Pydantic model
+    try:
+        request_model = AppwriteRequestModel.model_validate({
+            'method': req.method,
+            'headers': req.headers,
+            'path': req.path,
+            'url': req.url,
+            'body': req.body,
+            'bodyText': req.bodyText,
+            'bodyJson': req.bodyJson
+        })
+        log("Request validation successful")
+    except Exception as validation_error:
+        error(f"Request validation failed: {validation_error}")
+
     client = Client()
-    client.set_endpoint(req.env['APPWRITE_FUNCTION_ENDPOINT'])
-    client.set_project(req.env['APPWRITE_FUNCTION_PROJECT_ID'])
-    client.set_key(req.env['APPWRITE_FUNCTION_API_KEY'])
+    client.set_endpoint(os.getenv('APPWRITE_FUNCTION_ENDPOINT'))
+    client.set_project(os.getenv('APPWRITE_FUNCTION_PROJECT_ID'))
+    client.set_key(os.getenv('APPWRITE_FUNCTION_API_KEY'))
+
+    log(f"Processing {req.method} request to {req.path}")
 
     return res.json({
-        'message': 'Hello from Python function!'
+        'message': 'Hello from Python function!',
+        'functionName': '{{functionName}}',
+        'method': req.method,
+        'path': req.path,
+        'headers': req.headers
     })