appwrite-utils-cli 1.7.8 → 1.7.9

package/dist/functions/templates/count-docs-in-collection/src/main.ts

@@ -0,0 +1,159 @@
+import { Client, Databases, Query } from "node-appwrite";
+import { AppwriteRequest, type AppwriteResponse } from "appwrite-utils";
+import { requestSchema } from "./request.js";
+
+/**
+ * Main function to handle document counting requests.
+ * @param {Object} params - The function parameters.
+ * @param {Object} params.req - The request object.
+ * @param {Object} params.res - The response object.
+ * @param {Function} params.log - Logging function.
+ * @param {Function} params.error - Error logging function.
+ * @returns {Promise<Object>} JSON response with count or error message.
+ */
+export default async ({
+  req,
+  res,
+  log,
+  error,
+}: {
+  req: AppwriteRequest;
+  res: AppwriteResponse;
+  log: (message: string) => void;
+  error: (message: string) => void;
+}) => {
+  // Initialize Appwrite client
+  const client = new Client()
+    .setEndpoint(process.env["APPWRITE_FUNCTION_ENDPOINT"]!)
+    .setProject(process.env["APPWRITE_FUNCTION_PROJECT_ID"]!)
+    .setKey(req.headers["x-appwrite-key"] || "");
+
+  const databases = new Databases(client);
+
+  try {
+    if (req.method === "POST") {
+      // Parse request body
+      const body = requestSchema.safeParse(
+        typeof req.body === "string" ? JSON.parse(req.body) : req.body
+      );
+
+      if (!body.success) {
+        return res.json({ success: false, error: body.error }, 400);
+      }
+
+      const { databaseId, collectionId, queries = [] } = body.data;
+
+      log(`Queries: ${JSON.stringify(queries)}`);
+
+      // Count documents in the specified collection
+      const count = await countAllDocuments(
+        log,
+        databases,
+        databaseId,
+        collectionId,
+        queries
+      );
+
+      // Return successful response with document count
+      return res.json({
+        success: true,
+        count: count,
+      });
+    } else {
+      // Return error for non-POST requests
+      return res.json({ success: false, error: "Method not allowed" }, 405);
+    }
+  } catch (err) {
+    // Log and return any errors
+    error(`Error processing request: ${err}`);
+    return res.json({ success: false, error: (err as Error).message }, 500);
+  }
+};
+
+/**
+ * Counts all documents in a collection, handling large collections efficiently.
+ * @param {Function} log - Logging function.
+ * @param {Databases} databases - Appwrite Databases instance.
+ * @param {string} databaseId - ID of the database.
+ * @param {string} collectionId - ID of the collection.
+ * @param {string[]} queries - Array of query strings to filter documents.
+ * @param {number} batchSize - Size of batches for processing (default: 1000).
+ * @returns {Promise<number>} Total count of documents.
+ */
+async function countAllDocuments(
+  log: any,
+  databases: Databases,
+  databaseId: string,
+  collectionId: string,
+  queries: string[] = [],
+  batchSize: number = 1000
+): Promise<number> {
+  // Filter out limit and offset queries
+  const initialQueries = queries.filter(
+    (q) => !(q.includes("limit") || q.includes("offset"))
+  );
+
+  // Initial query to check if total is less than 5000
+  const initialResponse = await databases.listDocuments(
+    databaseId,
+    collectionId,
+    [...initialQueries, Query.limit(1)]
+  );
+
+  if (initialResponse.total < 5000) {
+    log(`Total documents (from initial response): ${initialResponse.total}`);
+    return initialResponse.total;
+  }
+
+  // If total is 5000 or more, we need to count manually
+  let bound = 5000;
+
+  // Exponential search to find an upper bound
+  while (true) {
+    log(`Querying for offset ${bound}`);
+    try {
+      const response = await databases.listDocuments(databaseId, collectionId, [
+        ...initialQueries,
+        Query.limit(1),
+        Query.offset(bound),
+      ]);
+
+      if (response.documents.length === 0) {
+        break;
+      }
+      bound *= 2;
+    } catch (error) {
+      break;
+    }
+  }
+
+  // Binary search to find the exact count
+  let low = Math.floor(bound / 2);
+  let high = bound;
+  let lastValidCount = low;
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    log(`Binary search: Querying for offset ${mid}`);
+
+    try {
+      const response = await databases.listDocuments(databaseId, collectionId, [
+        ...initialQueries,
+        Query.limit(1),
+        Query.offset(mid),
+      ]);
+
+      if (response.documents.length > 0) {
+        lastValidCount = mid + 1; // +1 because offset is 0-based
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    } catch (error) {
+      high = mid - 1;
+    }
+  }
+
+  log(`Total documents: ${lastValidCount}`);
+  return lastValidCount;
+}

package/dist/functions/templates/count-docs-in-collection/src/request.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const requestSchema = z.object({
+  databaseId: z.string(),
+  collectionId: z.string(),
+  queries: z.array(z.string()).optional(),
+});
+
+export type Request = z.infer<typeof requestSchema>;

package/dist/functions/templates/count-docs-in-collection/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/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/dist/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/dist/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/dist/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 });
+  }
+}