appwrite-utils-cli 1.7.7 → 1.7.9

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,
+  });
+}

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

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "checkJs": false,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noImplicitThis": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "moduleDetection": "force",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/functions/templates/uv/README.md

@@ -0,0 +1,31 @@
+# Python UV Function Template
+
+This is a Python template for Appwrite Functions using UV for fast dependency management.
+
+## Structure
+- `src/index.py`: Main function entry point
+- `pyproject.toml`: UV/PyPI project configuration and dependencies
+
+## Usage
+Your function will receive a context object with:
+- `req`: Request object containing request data, headers, and environment variables
+- `res`: Response object for sending responses
+- `log`: Function for logging (shows in your function logs)
+- `error`: Function for error logging
+
+## Example Request
+```json
+{
+  "key": "value"
+}
+```
+
+## Development
+1. Install UV: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+2. Install dependencies: `uv sync`
+3. Run locally: `uv run python src/index.py`
+4. Deploy: Dependencies will be installed during deployment
+
+## Deployment
+Make sure it's inside `appwriteConfig.yaml` functions array, and if you want to install dependencies FIRST, before Appwrite (using your system), you can
+add the `predeployCommands` to the function in `appwriteConfig.yaml`.

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

@@ -0,0 +1,30 @@
+[project]
+name = "{{functionName}}"
+version = "0.1.0"
+description = "Appwrite Python function using UV"
+authors = [{name = "Your Name", email = "you@example.com"}]
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "appwrite>=7.0.1",
+    "pydantic>=2.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=7.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]