@ketrics/ketrics-cli 0.2.3 → 0.4.0

package/templates/HelloWorld/frontend/src/App.tsx

@@ -1,141 +1,161 @@
 import { useState } from "react";
-import { z } from "zod";
 import { apiClient } from "./services";
 
-const inputSchema = z.string().min(1, "Input is required").max(100, "Max 100 characters");
-
 function App() {
-  const [input, setInput] = useState("");
   const [result, setResult] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
 
-  const handleSubmit = () => {
-    const validation = inputSchema.safeParse(input);
-    if (!validation.success) {
-      setError(validation.error.errors[0].message);
-      setResult(null);
-      return;
-    }
+  const runFunction = async (fnName: string, payload?: unknown) => {
+    setLoading(true);
     setError(null);
-    setResult(`You submitted: ${validation.data}`);
-  };
-
-  const handleRunEcho = async () => {
-    try {
-      const data = await apiClient.run("echo");
-      console.log("API Data:", data);
-    } catch (err) {
-      console.error("API Error:", err);
-    }
-  };
-
-  const handleRunSaveFile = async () => {
-    try {
-      const data = await apiClient.run("saveFile");
-      console.log("API Data:", data);
-    } catch (err) {
-      console.error("API Error:", err);
-    }
-  };
-
-  const handleRunReadFile = async () => {
-    try {
-      const data = await apiClient.run("readFile");
-      console.log("API Data:", data);
-    } catch (err) {
-      console.error("API Error:", err);
-    }
-  };
-
-  const handleRunGenerateDownloadUrl = async () => {
-    try {
-      const data = await apiClient.run("generateDownloadUrl");
-      // Trigger download of the file in the url data.result.url
-      const downloadUrl = data.result.url;
-      const link = document.createElement("a");
-      link.href = downloadUrl;
-      link.target = "_blank";
-      link.download = "data.json";
-      document.body.appendChild(link);
-      link.click();
-      document.body.removeChild(link);
-      console.log("downloadUrl:", downloadUrl);
-    } catch (err) {
-      console.error("API Error:", err);
-    }
-  };
-
-  const handleRunTestWriteFileWithoutVolumeGrant = async () => {
+    setResult(null);
     try {
-      const data = await apiClient.run("testWriteFileWithoutVolumeGrant");
-      console.log("API Data:", data);
+      const data = await apiClient.run(fnName, payload);
+      setResult(JSON.stringify(data, null, 2));
     } catch (err) {
-      console.error("API Error:", err);
+      setError(err instanceof Error ? err.message : "An error occurred");
+    } finally {
+      setLoading(false);
     }
   };
 
-  const handleGetSecret = async () => {
-    try {
-      const data = await apiClient.run("getSecret");
-      console.log("Secret Data:", data);
-    } catch (err) {
-      console.error("Secret Error:", err);
-    }
-  };
-
-  const handleGetSecretWithoutGrant = async () => {
+  const handleDownload = async (fnName: string, payload?: unknown) => {
+    setLoading(true);
+    setError(null);
+    setResult(null);
     try {
-      const data = await apiClient.run("getSecretWithoutGrant");
-      console.log("Secret Data:", data);
+      const data = await apiClient.run(fnName, payload);
+      const downloadUrl = data?.result?.downloadUrl;
+      if (downloadUrl) {
+        const link = document.createElement("a");
+        link.href = downloadUrl;
+        link.target = "_blank";
+        document.body.appendChild(link);
+        link.click();
+        document.body.removeChild(link);
+        setResult(`Download started. URL: ${downloadUrl}`);
+      } else {
+        setResult(JSON.stringify(data, null, 2));
+      }
     } catch (err) {
-      console.error("Secret Error:", err);
+      setError(err instanceof Error ? err.message : "An error occurred");
+    } finally {
+      setLoading(false);
     }
   };
 
   return (
     <div className="app">
-      <h1>Ketrics Test Application</h1>
-      <p className="subtitle">Frontend Demo with Zod Validation</p>
-
-      <div className="form">
-        <input type="text" value={input} onChange={(e) => setInput(e.target.value)} placeholder="Enter something..." className="input" />
-        <button onClick={handleSubmit} className="button">
-          Submit
-        </button>
-
-        <button onClick={handleRunEcho} className="button">
-          Test Echo API
-        </button>
-        <button onClick={handleRunSaveFile} className="button">
-          Test Save File API
-        </button>
-        <button onClick={handleRunReadFile} className="button">
-          Test Read File API
-        </button>
-        <button onClick={handleRunGenerateDownloadUrl} className="button">
-          Test Generate Download URL API
-        </button>
-        <button onClick={handleRunTestWriteFileWithoutVolumeGrant} className="button">
-          Test Write File Without Volume Grant API
-        </button>
-        <button onClick={handleGetSecret} className="button">
-          Get Secret with Grant
-        </button>
-        <button onClick={handleGetSecretWithoutGrant} className="button">
-          Get Secret without Grant
-        </button>
+      <h1>Ketrics Application</h1>
+      <p className="subtitle">SDK Feature Examples</p>
+
+      <div className="sections">
+        <div className="section">
+          <h2>General</h2>
+          <div className="button-group">
+            <button onClick={() => runFunction("echo", { message: "Hello!" })} className="button" disabled={loading}>
+              Echo
+            </button>
+            <button onClick={() => runFunction("info")} className="button" disabled={loading}>
+              Info
+            </button>
+            <button onClick={() => runFunction("fetchExternalApi")} className="button" disabled={loading}>
+              HTTP Request
+            </button>
+          </div>
+        </div>
+
+        <div className="section">
+          <h2>Volumes</h2>
+          <div className="button-group">
+            <button onClick={() => runFunction("saveFile")} className="button" disabled={loading}>
+              Save File
+            </button>
+            <button onClick={() => runFunction("readFile")} className="button" disabled={loading}>
+              Read File
+            </button>
+            <button onClick={() => runFunction("listFiles", { prefix: "output/" })} className="button" disabled={loading}>
+              List Files
+            </button>
+            <button onClick={() => handleDownload("generateDownloadUrl")} className="button" disabled={loading}>
+              Download File
+            </button>
+            <button onClick={() => runFunction("copyFile")} className="button" disabled={loading}>
+              Copy File
+            </button>
+          </div>
+        </div>
+
+        <div className="section">
+          <h2>Database</h2>
+          <div className="button-group">
+            <button onClick={() => runFunction("queryUsers", { limit: 5 })} className="button" disabled={loading}>
+              Query Users
+            </button>
+            <button onClick={() => runFunction("insertRecord", { name: "Test User", email: "test@example.com" })} className="button" disabled={loading}>
+              Insert Record
+            </button>
+            <button onClick={() => runFunction("transferFunds", { fromAccountId: 1, toAccountId: 2, amount: 100 })} className="button" disabled={loading}>
+              Transfer Funds
+            </button>
+          </div>
+        </div>
+
+        <div className="section">
+          <h2>Documents</h2>
+          <div className="button-group">
+            <button onClick={() => handleDownload("createSimplePdf")} className="button" disabled={loading}>
+              Create PDF
+            </button>
+            <button onClick={() => handleDownload("createInvoicePdf")} className="button" disabled={loading}>
+              Create Invoice PDF
+            </button>
+            <button onClick={() => handleDownload("createSpreadsheet")} className="button" disabled={loading}>
+              Create Spreadsheet
+            </button>
+            <button onClick={() => handleDownload("exportDataToExcel")} className="button" disabled={loading}>
+              Export to Excel
+            </button>
+          </div>
+        </div>
+
+        <div className="section">
+          <h2>Messaging & Jobs</h2>
+          <div className="button-group">
+            <button onClick={() => runFunction("sendNotification", { subject: "Test", body: "Hello from the app!" })} className="button" disabled={loading}>
+              Send Notification
+            </button>
+            <button onClick={() => runFunction("scheduleBackgroundJob")} className="button" disabled={loading}>
+              Schedule Job
+            </button>
+            <button onClick={() => runFunction("getSecret")} className="button" disabled={loading}>
+              Get Secret
+            </button>
+          </div>
+        </div>
       </div>
 
+      {loading && <p className="loading">Running...</p>}
       {error && <p className="error">{error}</p>}
-      {result && <p className="result">{result}</p>}
+      {result && (
+        <div className="result">
+          <pre>{result}</pre>
+        </div>
+      )}
 
       <div className="info">
         <h2>About</h2>
-        <p>This is a test application for the Ketrics platform. It demonstrates:</p>
+        <p>This application demonstrates the Ketrics SDK features:</p>
         <ul>
-          <li>React + TypeScript + Vite setup</li>
-          <li>Zod schema validation</li>
-          <li>Deployment via Ketrics CLI</li>
+          <li>Volume storage (save, read, list, download, copy files)</li>
+          <li>Database connections (query, insert, transactions)</li>
+          <li>PDF document generation (simple and invoice-style)</li>
+          <li>Excel workbook creation (single and multi-sheet)</li>
+          <li>User messaging and notifications</li>
+          <li>Background job scheduling</li>
+          <li>Secret management</li>
+          <li>External HTTP requests</li>
         </ul>
       </div>
     </div>

package/templates/HelloWorld/frontend/src/mocks/handlers.ts

@@ -0,0 +1,149 @@
+/**
+ * Mock Backend Handlers
+ *
+ * Define mock responses for your backend functions here.
+ * These are used automatically when running `npm run dev` (local development)
+ * and are completely excluded from production builds.
+ *
+ * Each key corresponds to a backend function name exported from backend/src/index.ts.
+ * The handler receives the same payload your backend function would receive
+ * and should return the same response shape.
+ *
+ * Usage:
+ *   1. Add a handler for each backend function you want to mock
+ *   2. Run `npm run dev` - the frontend will use these handlers instead of the runtime API
+ *   3. Run `npm run build` / `ketrics deploy` - mock code is stripped out entirely
+ */
+
+type MockHandler = (payload?: unknown) => unknown | Promise<unknown>;
+
+const handlers: Record<string, MockHandler> = {
+  echo: (payload) => ({
+    payload,
+    context: {
+      tenant: { id: "mock-tenant-id", code: "mock-tenant", name: "Mock Tenant" },
+      application: { id: "mock-app-id", code: "mock-app", name: "Mock App", version: "1.0.0", deploymentId: "mock-deploy" },
+      requestor: { type: "user", userId: "mock-user-id", email: "dev@localhost", name: "Local Developer", applicationPermissions: [] },
+      runtime: { nodeVersion: "18.x", runtime: "mock", region: "local" },
+      environment: {},
+    },
+  }),
+
+  info: () => ({
+    tenant: { id: "mock-tenant-id", code: "mock-tenant", name: "Mock Tenant" },
+    application: { id: "mock-app-id", code: "mock-app", name: "Mock App", version: "1.0.0" },
+    runtime: { nodeVersion: "18.x", runtime: "mock", region: "local" },
+  }),
+
+  fetchExternalApi: () => ({
+    data: { id: 1, title: "Mock Post", body: "This is a mock response from the local dev server." },
+    fetchedAt: new Date().toISOString(),
+  }),
+
+  // --- Volumes ---
+
+  saveFile: () => ({
+    jsonFile: { key: "output/data.json", etag: "mock-etag-1", size: 128 },
+    textFile: { key: "output/hello.txt", etag: "mock-etag-2", size: 19 },
+  }),
+
+  readFile: () => ({
+    contentType: "application/json",
+    contentLength: 128,
+    lastModified: new Date().toISOString(),
+    parsed: { generatedBy: "mock-app", generatedAt: new Date().toISOString(), tenant: "mock-tenant" },
+  }),
+
+  listFiles: (payload: unknown) => {
+    const { prefix } = (payload as { prefix?: string }) || {};
+    return {
+      files: [
+        { key: `${prefix || "output/"}data.json`, size: 128, lastModified: new Date().toISOString(), contentType: "application/json" },
+        { key: `${prefix || "output/"}hello.txt`, size: 19, lastModified: new Date().toISOString(), contentType: "text/plain" },
+      ],
+      count: 2,
+      isTruncated: false,
+    };
+  },
+
+  generateDownloadUrl: () => ({
+    url: "https://example.com/mock-download-url",
+    expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+  }),
+
+  copyFile: () => ({
+    sourceKey: "output/data.json",
+    destinationKey: "backup/data-backup.json",
+    etag: "mock-etag-copy",
+  }),
+
+  // --- Database ---
+
+  queryUsers: (payload: unknown) => {
+    const { limit } = (payload as { limit?: number }) || {};
+    const users = [
+      { id: 1, name: "Alice Johnson", email: "alice@example.com" },
+      { id: 2, name: "Bob Smith", email: "bob@example.com" },
+      { id: 3, name: "Carol Davis", email: "carol@example.com" },
+      { id: 4, name: "Dan Wilson", email: "dan@example.com" },
+      { id: 5, name: "Eve Martinez", email: "eve@example.com" },
+    ];
+    const sliced = users.slice(0, limit || 10);
+    return { users: sliced, rowCount: sliced.length };
+  },
+
+  insertRecord: (payload: unknown) => {
+    const { name, email } = (payload as { name?: string; email?: string }) || {};
+    if (!name || !email) throw new Error("name and email are required");
+    return { affectedRows: 1, insertId: Math.floor(Math.random() * 1000) + 100 };
+  },
+
+  transferFunds: (payload: unknown) => {
+    const { amount } = (payload as { amount?: number }) || {};
+    if (!amount || amount <= 0) throw new Error("Amount must be positive");
+    return { transferred: amount };
+  },
+
+  // --- Documents ---
+
+  createSimplePdf: () => ({
+    downloadUrl: "https://example.com/mock-simple.pdf",
+    message: "[Mock] PDF would be generated by the backend",
+  }),
+
+  createInvoicePdf: () => ({
+    downloadUrl: "https://example.com/mock-invoice.pdf",
+    message: "[Mock] Invoice PDF would be generated by the backend",
+  }),
+
+  createSpreadsheet: () => ({
+    downloadUrl: "https://example.com/mock-spreadsheet.xlsx",
+    message: "[Mock] Spreadsheet would be generated by the backend",
+  }),
+
+  exportDataToExcel: () => ({
+    downloadUrl: "https://example.com/mock-export.xlsx",
+    message: "[Mock] Excel export would be generated by the backend",
+  }),
+
+  // --- Messaging & Jobs ---
+
+  sendNotification: (payload: unknown) => {
+    const { subject, body } = (payload as { subject?: string; body?: string }) || {};
+    return { sent: true, subject, body, message: "[Mock] Notification would be sent by the backend" };
+  },
+
+  scheduleBackgroundJob: () => ({
+    jobId: `mock-job-${Date.now()}`,
+    status: "scheduled",
+    message: "[Mock] Job would be scheduled by the backend",
+  }),
+
+  getSecret: () => ({
+    value: "mock-secret-value",
+    message: "[Mock] Secret would be retrieved from the backend",
+  }),
+};
+
+export { handlers };
+export type { MockHandler };

package/templates/HelloWorld/frontend/src/mocks/mock-client.ts

@@ -0,0 +1,45 @@
+/**
+ * Mock API Client
+ *
+ * Replaces the real API client during local development (`npm run dev`).
+ * Routes function calls to the mock handlers defined in ./handlers.ts
+ * instead of making HTTP requests to the Ketrics Runtime API.
+ *
+ * This file is tree-shaken out of production builds by Vite.
+ */
+
+import { handlers } from "./handlers";
+
+class MockAPIClient {
+  async run(fnName: string, payload?: unknown) {
+    const handler = handlers[fnName];
+
+    if (!handler) {
+      throw new Error(
+        `[Mock] No handler defined for "${fnName}". ` +
+        `Add it to src/mocks/handlers.ts to use it in local development.`
+      );
+    }
+
+    // Simulate network latency
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    try {
+      const result = await handler(payload);
+      console.log(`[Mock] ${fnName}`, { payload, result });
+      return { success: true, result };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[Mock] ${fnName} error:`, message);
+      throw new Error(message);
+    }
+  }
+}
+
+export function createMockClient() {
+  console.log(
+    "%c[Ketrics] Running with mock backend — edit src/mocks/handlers.ts to customize responses",
+    "color: #f59e0b; font-weight: bold;"
+  );
+  return new MockAPIClient();
+}

package/templates/HelloWorld/frontend/src/services/index.ts

@@ -1,25 +1,20 @@
 import { createAuthManager } from "@ketrics/sdk-frontend";
-import axios from "axios";
 
-const auth = createAuthManager();
-
-// Initialize auto-refresh
-auth.initAutoRefresh({
-  refreshBuffer: 60,
-  onTokenUpdated: (token) => {
-    // Update your HTTP client headers
-    axios.defaults.headers.common["Authorization"] = `Bearer ${token}`;
-  },
-});
+interface APIClientInterface {
+  run(fnName: string, payload?: unknown): Promise<unknown>;
+}
 
-class APIClient {
+// ---------------------------------------------------------------------------
+// Real API Client — used when deployed (production builds)
+// ---------------------------------------------------------------------------
+class APIClient implements APIClientInterface {
   private auth;
 
-  constructor(authManager: typeof auth) {
+  constructor(authManager: ReturnType<typeof createAuthManager>) {
     this.auth = authManager;
   }
 
-  private async makeRequest(fnName: string) {
+  private async makeRequest(fnName: string, payload?: unknown) {
     const runtimeApiUrl = this.auth.getRuntimeApiUrl();
     const tenantId = this.auth.getTenantId();
     const applicationId = this.auth.getApplicationId();
@@ -32,24 +27,47 @@ class APIClient {
     const response = await fetch(`${runtimeApiUrl}/tenants/${tenantId}/applications/${applicationId}/functions/${fnName}`, {
       method: "POST",
       headers: {
-        Authorization: `Bearer ${accessToken}`,
+        "Authorization": `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
       },
+      body: JSON.stringify({ payload: payload ?? null }),
     });
 
     if (!response.ok) {
-      throw new Error(`API request failed with status ${response.status}`);
+      const errorBody = await response.json().catch(() => null);
+      const message = errorBody?.error?.message || `API request failed with status ${response.status}`;
+      throw new Error(message);
     }
 
     return response.json();
   }
 
-  async run(fnName: string) {
-    const response = await this.makeRequest(fnName);
+  async run(fnName: string, payload?: unknown) {
+    return this.makeRequest(fnName, payload);
+  }
+}
 
-    return response;
+// ---------------------------------------------------------------------------
+// Client initialization — mock in dev, real in production
+// ---------------------------------------------------------------------------
+async function createClient(): Promise<APIClientInterface> {
+  if (import.meta.env.DEV) {
+    // Dynamic import keeps mock code in a separate chunk that Vite
+    // completely excludes from production builds.
+    const { createMockClient } = await import("../mocks/mock-client");
+    return createMockClient();
   }
+
+  const auth = createAuthManager();
+  auth.initAutoRefresh({
+    refreshBuffer: 60,
+    onTokenUpdated: () => {
+      // Token is refreshed automatically and retrieved via getAccessToken()
+    },
+  });
+  return new APIClient(auth);
 }
 
-const apiClient = new APIClient(auth);
+const apiClient = await createClient();
 
 export { apiClient };

package/templates/HelloWorld/frontend/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/HelloWorld/tests/test.createInvoicePdf.json

@@ -0,0 +1,18 @@
+{
+  "endpoint": "/tenants/{{tenantId}}/applications/{{applicationId}}/functions/createInvoicePdf",
+  "method": "POST",
+  "headers": {
+    "Authorization": "Bearer {{token}}",
+    "Content-Type": "application/json"
+  },
+  "body": {
+    "payload": {
+      "invoiceNumber": "INV-100",
+      "customerName": "Acme Corp",
+      "items": [
+        { "description": "Consulting", "quantity": 10, "price": 200 },
+        { "description": "Development", "quantity": 40, "price": 150 }
+      ]
+    }
+  }
+}

package/templates/HelloWorld/tests/{test.getSecretWithoutGrant.json → test.createSimplePdf.json}

@@ -1,9 +1,11 @@
 {
-  "endpoint": "/tenants/{{tenantId}}/applications/{{applicationId}}/functions/getSecretWithoutGrant",
+  "endpoint": "/tenants/{{tenantId}}/applications/{{applicationId}}/functions/createSimplePdf",
   "method": "POST",
   "headers": {
     "Authorization": "Bearer {{token}}",
     "Content-Type": "application/json"
   },
-  "body": {}
+  "body": {
+    "payload": null
+  }
 }

package/templates/HelloWorld/tests/test.createSpreadsheet.json

@@ -0,0 +1,11 @@
+{
+  "endpoint": "/tenants/{{tenantId}}/applications/{{applicationId}}/functions/createSpreadsheet",
+  "method": "POST",
+  "headers": {
+    "Authorization": "Bearer {{token}}",
+    "Content-Type": "application/json"
+  },
+  "body": {
+    "payload": null
+  }
+}

package/templates/HelloWorld/tests/test.echo.json

@@ -6,8 +6,8 @@
     "Content-Type": "application/json"
   },
   "body": {
-    "data": {
-      "hello": "world"
+    "payload": {
+      "message": "Hello, World!"
     }
   }
 }

package/templates/HelloWorld/tests/test.fetchExternalApi.json

@@ -0,0 +1,13 @@
+{
+  "endpoint": "/tenants/{{tenantId}}/applications/{{applicationId}}/functions/fetchExternalApi",
+  "method": "POST",
+  "headers": {
+    "Authorization": "Bearer {{token}}",
+    "Content-Type": "application/json"
+  },
+  "body": {
+    "payload": {
+      "url": "https://jsonplaceholder.typicode.com/posts/1"
+    }
+  }
+}

package/templates/HelloWorld/tests/test.getSecret.json

@@ -5,5 +5,9 @@
     "Authorization": "Bearer {{token}}",
     "Content-Type": "application/json"
   },
-  "body": {}
+  "body": {
+    "payload": {
+      "code": "apikey"
+    }
+  }
 }

package/templates/HelloWorld/tests/test.info.json

@@ -5,5 +5,7 @@
     "Authorization": "Bearer {{token}}",
     "Content-Type": "application/json"
   },
-  "body": {}
+  "body": {
+    "payload": null
+  }
 }

package/templates/HelloWorld/tests/test.listFiles.json

@@ -0,0 +1,13 @@
+{
+  "endpoint": "/tenants/{{tenantId}}/applications/{{applicationId}}/functions/listFiles",
+  "method": "POST",
+  "headers": {
+    "Authorization": "Bearer {{token}}",
+    "Content-Type": "application/json"
+  },
+  "body": {
+    "payload": {
+      "prefix": "output/"
+    }
+  }
+}