appwrite-utils-cli 1.5.1 → 1.6.0

package/src/functions/templates/hono-typescript/README.md

@@ -0,0 +1,286 @@
+# {{functionName}} - Hono + Appwrite Function
+
+This is an Appwrite TypeScript function built with the [Hono](https://hono.dev) web framework. Hono provides a fast, lightweight, and modern way to build web APIs with excellent TypeScript support.
+
+## Features
+
+- 🚀 **Ultra-fast routing** with Hono framework
+- 🔒 **Built-in Appwrite integration** with context injection
+- 📝 **Full TypeScript support** with type safety
+- 🛠️ **Comprehensive middleware** for logging, error handling, and Appwrite context
+- 🔧 **Request/Response adapters** for seamless integration
+- 📊 **Example API endpoints** with database operations
+
+## Project Structure
+
+```
+src/
+├── index.ts              # Main Appwrite function entry point
+├── app.ts                # Hono application with routes
+├── context.ts            # Appwrite context type definitions
+├── adapters/
+│   ├── request.ts        # Appwrite → Hono request conversion
+│   └── response.ts       # Hono → Appwrite response conversion
+└── middleware/
+    └── appwrite.ts       # Appwrite context middleware
+```
+
+## Getting Started
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Available Routes
+
+- `GET /` - Welcome message with function info
+- `GET /health` - Health check endpoint
+- `GET /api/user` - Get current authenticated user (requires user session)
+- `POST /api/webhook` - Generic webhook handler
+- `GET /api/databases` - List databases (requires API key)
+- `POST /api/data/:databaseId/:collectionId` - Create document
+- `GET /api/data/:databaseId/:collectionId` - List documents
+
+### 3. Development
+
+```bash
+npm run dev
+```
+
+### 4. Build
+
+```bash
+npm run build
+```
+
+## Adding New Routes
+
+You can easily add new routes to your Hono app in `src/app.ts`:
+
+```typescript
+// GET endpoint
+app.get("/api/hello/:name", (c) => {
+  const name = c.req.param("name");
+  c.log(`Hello endpoint called for ${name}`);
+
+  return c.json({
+    message: `Hello, ${name}!`,
+    timestamp: new Date().toISOString(),
+  });
+});
+
+// POST endpoint with JSON body
+app.post("/api/items", async (c) => {
+  const data = await c.req.json();
+
+  // Access Appwrite context
+  const { databases } = getAppwriteClient(c);
+
+  try {
+    const document = await databases.createDocument(
+      "database-id",
+      "collection-id",
+      "unique()",
+      data
+    );
+
+    c.log("Item created successfully");
+    return c.json({ item: document }, 201);
+  } catch (error) {
+    c.error(`Failed to create item: ${error}`);
+    return c.json({ error: "Failed to create item" }, 500);
+  }
+});
+```
+
+## Middleware
+
+The template includes several built-in middleware:
+
+### Appwrite Context Middleware
+Automatically injects Appwrite context into every Hono request:
+
+```typescript
+// Access Appwrite context in any route handler
+app.get("/api/example", (c) => {
+  const appwriteContext = c.get("appwriteContext");
+
+  // Use Appwrite logging
+  c.log("This will appear in Appwrite function logs");
+  c.error("This will appear as an error in Appwrite logs");
+
+  // Access Appwrite headers
+  const userId = c.appwrite.userId;
+  const isAuthenticated = c.appwrite.isUserAuthenticated();
+
+  return c.json({ userId, isAuthenticated });
+});
+```
+
+### Request Logging
+Automatically logs incoming requests and responses with timing:
+
+```
+→ GET /api/user
+← GET /api/user 200 (45ms)
+```
+
+### Error Handling
+Catches and properly formats errors:
+
+```typescript
+app.get("/api/error-example", (c) => {
+  throw new Error("Something went wrong");
+  // This will be automatically caught and returned as:
+  // { error: "Internal Server Error", message: "Something went wrong", ... }
+});
+```
+
+## Appwrite Integration
+
+### Authentication
+
+Check if a user is authenticated:
+
+```typescript
+app.get("/api/protected", (c) => {
+  if (!c.appwrite.isUserAuthenticated()) {
+    return c.json({ error: "Authentication required" }, 401);
+  }
+
+  const userId = c.appwrite.userId;
+  return c.json({ message: `Hello user ${userId}` });
+});
+```
+
+### API Key Access
+
+Check if request has valid API key:
+
+```typescript
+app.get("/api/admin", (c) => {
+  if (!c.appwrite.isApiKeyRequest()) {
+    return c.json({ error: "API key required" }, 401);
+  }
+
+  // Admin operations here
+  return c.json({ message: "Admin access granted" });
+});
+```
+
+### Database Operations
+
+```typescript
+app.post("/api/posts", async (c) => {
+  const data = await c.req.json();
+  const { databases } = getAppwriteClient(c);
+
+  try {
+    const post = await databases.createDocument(
+      "blog-db",
+      "posts",
+      "unique()",
+      {
+        title: data.title,
+        content: data.content,
+        authorId: c.appwrite.userId,
+        createdAt: new Date().toISOString(),
+      }
+    );
+
+    return c.json({ post }, 201);
+  } catch (error) {
+    c.error(`Failed to create post: ${error}`);
+    return c.json({ error: "Failed to create post" }, 500);
+  }
+});
+```
+
+## Environment Variables
+
+The following environment variables are automatically available:
+
+- `APPWRITE_FUNCTION_ENDPOINT` - Appwrite server endpoint
+- `APPWRITE_FUNCTION_PROJECT_ID` - Current project ID
+- `APPWRITE_FUNCTION_API_KEY` - Function API key
+- `APPWRITE_FUNCTION_ID` - Current function ID
+- `APPWRITE_FUNCTION_NAME` - Function name
+
+## Response Types
+
+Hono provides several response helpers:
+
+```typescript
+// JSON response
+return c.json({ data: "value" });
+
+// Text response
+return c.text("Hello World");
+
+// HTML response
+return c.html("<h1>Hello</h1>");
+
+// Redirect
+return c.redirect("/new-url");
+
+// Custom status
+return c.json({ error: "Not found" }, 404);
+
+// Custom headers
+return c.json({ data: "value" }, 200, {
+  "X-Custom-Header": "value"
+});
+```
+
+## Advanced Usage
+
+### Custom Middleware
+
+```typescript
+const authMiddleware = () => {
+  return async (c, next) => {
+    const token = c.req.header("Authorization");
+
+    if (!token) {
+      return c.json({ error: "Missing token" }, 401);
+    }
+
+    // Validate token logic here
+    c.set("user", { id: "123", email: "user@example.com" });
+
+    await next();
+  };
+};
+
+// Apply to specific routes
+app.use("/api/protected/*", authMiddleware());
+```
+
+### Path Parameters and Query Strings
+
+```typescript
+// Path parameters
+app.get("/api/users/:id/posts/:postId", (c) => {
+  const userId = c.req.param("id");
+  const postId = c.req.param("postId");
+
+  return c.json({ userId, postId });
+});
+
+// Query parameters
+app.get("/api/search", (c) => {
+  const query = c.req.query("q");
+  const page = parseInt(c.req.query("page") || "1");
+  const limit = parseInt(c.req.query("limit") || "10");
+
+  return c.json({ query, page, limit });
+});
+```
+
+## Learn More
+
+- [Hono Documentation](https://hono.dev/docs)
+- [Appwrite Functions Documentation](https://appwrite.io/docs/functions)
+- [TypeScript Documentation](https://www.typescriptlang.org/docs/)

package/src/functions/templates/hono-typescript/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{functionName}}",
+  "version": "1.0.0",
+  "description": "Appwrite TypeScript function with Hono web framework",
+  "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",
+    "hono": "^4.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/functions/templates/hono-typescript/src/adapters/request.ts

@@ -0,0 +1,74 @@
+import type { AppwriteRequest } from "../context.js";
+
+/**
+ * Convert Appwrite request to Web API Request for Hono
+ */
+export function convertAppwriteToWebRequest(appwriteReq: AppwriteRequest): Request {
+  // Construct the URL
+  const protocol = appwriteReq.scheme || "https";
+  const host = appwriteReq.host || "localhost";
+  const port = appwriteReq.port ? `:${appwriteReq.port}` : "";
+  const path = appwriteReq.path || "/";
+  const queryString = appwriteReq.queryString ? `?${appwriteReq.queryString}` : "";
+
+  const url = `${protocol}://${host}${port}${path}${queryString}`;
+
+  // Prepare headers
+  const headers = new Headers();
+  if (appwriteReq.headers) {
+    Object.entries(appwriteReq.headers).forEach(([key, value]) => {
+      if (value) {
+        headers.set(key, value);
+      }
+    });
+  }
+
+  // Prepare body for POST/PUT/PATCH requests
+  let body: string | undefined;
+  if (appwriteReq.method !== "GET" && appwriteReq.method !== "HEAD") {
+    if (appwriteReq.bodyText) {
+      body = appwriteReq.bodyText;
+    } else if (appwriteReq.bodyJson) {
+      body = typeof appwriteReq.bodyJson === "string"
+        ? appwriteReq.bodyJson
+        : JSON.stringify(appwriteReq.bodyJson);
+      if (!headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+      }
+    } else if (appwriteReq.body) {
+      body = typeof appwriteReq.body === "string"
+        ? appwriteReq.body
+        : JSON.stringify(appwriteReq.body);
+    }
+  }
+
+  // Create Web API Request
+  const request = new Request(url, {
+    method: appwriteReq.method,
+    headers,
+    body,
+  });
+
+  return request;
+}
+
+/**
+ * Extract path parameters from Hono context for Appwrite compatibility
+ */
+export function extractPathParams(honoParams: Record<string, string>): Record<string, string> {
+  return honoParams;
+}
+
+/**
+ * Extract query parameters from URL for Appwrite compatibility
+ */
+export function extractQueryParams(url: string): Record<string, string> {
+  const urlObj = new URL(url);
+  const params: Record<string, string> = {};
+
+  urlObj.searchParams.forEach((value, key) => {
+    params[key] = value;
+  });
+
+  return params;
+}

package/src/functions/templates/hono-typescript/src/adapters/response.ts

@@ -0,0 +1,106 @@
+import type { AppwriteResponse } from "../context.js";
+
+/**
+ * Convert Hono Response to Appwrite response format
+ */
+export async function convertWebResponseToAppwrite(
+  honoResponse: Response,
+  appwriteRes: AppwriteResponse
+): Promise<void> {
+  const status = honoResponse.status;
+  const headers: Record<string, string> = {};
+
+  // Extract headers from Hono response
+  honoResponse.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+
+  // Get content type to determine response handling
+  const contentType = honoResponse.headers.get("content-type") || "";
+
+  try {
+    // Handle different response types based on content-type
+    if (contentType.includes("application/json")) {
+      const data = await honoResponse.json();
+      return appwriteRes.json(data, status, headers);
+    } else if (contentType.includes("text/")) {
+      const text = await honoResponse.text();
+      return appwriteRes.text(text, status, headers);
+    } else if (contentType.includes("application/octet-stream") || contentType.includes("image/") || contentType.includes("video/")) {
+      const arrayBuffer = await honoResponse.arrayBuffer();
+      const bytes = new Uint8Array(arrayBuffer);
+      return appwriteRes.binary(bytes);
+    } else {
+      // Default to text for unknown content types
+      const text = await honoResponse.text();
+      return appwriteRes.text(text, status, headers);
+    }
+  } catch (error) {
+    // If response body parsing fails, return empty response
+    console.error("Error converting Hono response:", error);
+    return appwriteRes.empty();
+  }
+}
+
+/**
+ * Helper function to create common response types for Hono handlers
+ */
+export class AppwriteResponseHelpers {
+  /**
+   * Create a JSON response helper
+   */
+  static json(data: any, status: number = 200, headers?: Record<string, string>) {
+    const responseHeaders = new Headers(headers);
+    responseHeaders.set("content-type", "application/json");
+
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: responseHeaders,
+    });
+  }
+
+  /**
+   * Create a text response helper
+   */
+  static text(text: string, status: number = 200, headers?: Record<string, string>) {
+    const responseHeaders = new Headers(headers);
+    responseHeaders.set("content-type", "text/plain");
+
+    return new Response(text, {
+      status,
+      headers: responseHeaders,
+    });
+  }
+
+  /**
+   * Create an HTML response helper
+   */
+  static html(html: string, status: number = 200, headers?: Record<string, string>) {
+    const responseHeaders = new Headers(headers);
+    responseHeaders.set("content-type", "text/html");
+
+    return new Response(html, {
+      status,
+      headers: responseHeaders,
+    });
+  }
+
+  /**
+   * Create a redirect response helper
+   */
+  static redirect(url: string, status: number = 302) {
+    return new Response(null, {
+      status,
+      headers: {
+        location: url,
+      },
+    });
+  }
+
+  /**
+   * Create an empty response helper
+   */
+  static empty(status: number = 204) {
+    return new Response(null, { status });
+  }
+}

package/src/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);
+});