@ketrics/ketrics-cli 0.3.0 → 0.5.0

package/dist/src/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAgEnC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAyEnC"}

package/dist/src/cli.js

@@ -12,6 +12,7 @@ const build_1 = require("./commands/build");
 const deploy_1 = require("./commands/deploy");
 const validate_1 = require("./commands/validate");
 const run_1 = require("./commands/run");
+const update_1 = require("./commands/update");
 const version_1 = require("./version");
 /**
  * Create and configure CLI program
@@ -72,6 +73,14 @@ function createCLI() {
             verbose: options.verbose,
         });
     });
+    // Update command
+    program
+        .command("update")
+        .description("Update Ketrics CLI to the latest version")
+        .option("--check", "Show the currently installed version without updating")
+        .action(async (options) => {
+        await (0, update_1.updateCommand)({ check: options.check });
+    });
     return program;
 }
 //# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAaH,8BAgEC;AA3ED,yCAAoC;AACpC,8CAAkD;AAClD,4CAAgD;AAChD,8CAAkD;AAClD,kDAAsD;AACtD,wCAA4C;AAC5C,uCAAoC;AAEpC;;GAEG;AACH,SAAgB,SAAS;IACvB,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,WAAW,CAAC,yDAAyD,CAAC;SACtE,OAAO,CAAC,iBAAO,EAAE,eAAe,EAAE,kBAAkB,CAAC,CAAC;IAEzD,iBAAiB;IACjB,OAAO;SACJ,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,kDAAkD,CAAC;SAC/D,MAAM,CAAC,uBAAuB,EAAE,oDAAoD,CAAC;SACrF,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;QACjC,MAAM,IAAA,sBAAa,EAAC,OAAO,EAAE;YAC3B,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,gBAAgB;IAChB,OAAO;SACJ,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,8CAA8C,CAAC;SAC3D,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,IAAA,oBAAY,GAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEL,iBAAiB;IACjB,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,8CAA8C,CAAC;SAC3D,MAAM,CAAC,kBAAkB,EAAE,mBAAmB,CAAC;SAC/C,MAAM,CAAC,WAAW,EAAE,yDAAyD,CAAC;SAC9E,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxB,MAAM,IAAA,sBAAa,EAAC;YAClB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,mBAAmB;IACnB,OAAO;SACJ,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,uCAAuC,CAAC;SACpD,MAAM,CAAC,qBAAqB,EAAE,6BAA6B,CAAC;SAC5D,MAAM,CAAC,kBAAkB,EAAE,mBAAmB,CAAC;SAC/C,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxB,MAAM,IAAA,0BAAe,EAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEL,cAAc;IACd,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CAAC,uDAAuD,CAAC;SACpE,MAAM,CAAC,kBAAkB,EAAE,mBAAmB,CAAC;SAC/C,MAAM,CAAC,eAAe,EAAE,4CAA4C,CAAC;SACrE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE;QAClC,MAAM,IAAA,gBAAU,EAAC,QAAQ,EAAE;YACzB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAcH,8BAyEC;AArFD,yCAAoC;AACpC,8CAAkD;AAClD,4CAAgD;AAChD,8CAAkD;AAClD,kDAAsD;AACtD,wCAA4C;AAC5C,8CAAkD;AAClD,uCAAoC;AAEpC;;GAEG;AACH,SAAgB,SAAS;IACvB,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,WAAW,CAAC,yDAAyD,CAAC;SACtE,OAAO,CAAC,iBAAO,EAAE,eAAe,EAAE,kBAAkB,CAAC,CAAC;IAEzD,iBAAiB;IACjB,OAAO;SACJ,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,kDAAkD,CAAC;SAC/D,MAAM,CAAC,uBAAuB,EAAE,oDAAoD,CAAC;SACrF,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;QACjC,MAAM,IAAA,sBAAa,EAAC,OAAO,EAAE;YAC3B,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,gBAAgB;IAChB,OAAO;SACJ,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,8CAA8C,CAAC;SAC3D,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,IAAA,oBAAY,GAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEL,iBAAiB;IACjB,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,8CAA8C,CAAC;SAC3D,MAAM,CAAC,kBAAkB,EAAE,mBAAmB,CAAC;SAC/C,MAAM,CAAC,WAAW,EAAE,yDAAyD,CAAC;SAC9E,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxB,MAAM,IAAA,sBAAa,EAAC;YAClB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,mBAAmB;IACnB,OAAO;SACJ,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,uCAAuC,CAAC;SACpD,MAAM,CAAC,qBAAqB,EAAE,6BAA6B,CAAC;SAC5D,MAAM,CAAC,kBAAkB,EAAE,mBAAmB,CAAC;SAC/C,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxB,MAAM,IAAA,0BAAe,EAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEL,cAAc;IACd,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CAAC,uDAAuD,CAAC;SACpE,MAAM,CAAC,kBAAkB,EAAE,mBAAmB,CAAC;SAC/C,MAAM,CAAC,eAAe,EAAE,4CAA4C,CAAC;SACrE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE;QAClC,MAAM,IAAA,gBAAU,EAAC,QAAQ,EAAE;YACzB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,iBAAiB;IACjB,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,0CAA0C,CAAC;SACvD,MAAM,CAAC,SAAS,EAAE,uDAAuD,CAAC;SAC1E,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxB,MAAM,IAAA,sBAAa,EAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEL,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/commands/update.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Update Command
+ *
+ * Updates the Ketrics CLI to the latest version from npm.
+ */
+export interface UpdateOptions {
+    check?: boolean;
+}
+/**
+ * Execute update command
+ */
+export declare function updateCommand(options?: UpdateOptions): Promise<void>;
+//# sourceMappingURL=update.d.ts.map

package/dist/src/commands/update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/commands/update.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuE9E"}

package/dist/src/commands/update.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Update Command
+ *
+ * Updates the Ketrics CLI to the latest version from npm.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateCommand = updateCommand;
+const child_process_1 = require("child_process");
+const logger_1 = require("../utils/logger");
+const spinner_1 = require("../utils/spinner");
+const version_1 = require("../version");
+const PACKAGE_NAME = '@ketrics/ketrics-cli';
+/**
+ * Fetch the latest version from the npm registry
+ */
+async function getLatestVersion() {
+    const output = (0, child_process_1.execSync)(`npm view ${PACKAGE_NAME} version`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return output.trim();
+}
+/**
+ * Execute update command
+ */
+async function updateCommand(options = {}) {
+    const currentVersion = version_1.VERSION;
+    logger_1.logger.info(`Current version: ${currentVersion}`);
+    if (options.check) {
+        return;
+    }
+    logger_1.logger.newline();
+    // Check for latest version
+    let latestVersion;
+    try {
+        latestVersion = await (0, spinner_1.withSpinner)('Checking for updates...', () => getLatestVersion(), 'Checked for updates');
+    }
+    catch {
+        logger_1.logger.error('Failed to check for updates. Ensure you have internet access and npm is installed.');
+        process.exit(1);
+    }
+    logger_1.logger.keyValue('Latest version', latestVersion);
+    logger_1.logger.newline();
+    // Compare versions
+    if (currentVersion === latestVersion) {
+        logger_1.logger.success('You are already on the latest version!');
+        return;
+    }
+    // Install latest version
+    logger_1.logger.info(`Updating ${currentVersion} → ${latestVersion}...`);
+    logger_1.logger.newline();
+    try {
+        await (0, spinner_1.withSpinner)('Installing latest version...', async () => {
+            (0, child_process_1.execSync)(`npm install -g ${PACKAGE_NAME}@latest`, {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }, 'Installed latest version');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('EACCES') || message.includes('permission')) {
+            logger_1.logger.error('Permission denied. Try running with sudo:');
+            logger_1.logger.newline();
+            logger_1.logger.indent(`sudo npm install -g ${PACKAGE_NAME}@latest`, 1);
+        }
+        else {
+            logger_1.logger.error('Failed to update. You can try manually:');
+            logger_1.logger.newline();
+            logger_1.logger.indent(`npm install -g ${PACKAGE_NAME}@latest`, 1);
+        }
+        process.exit(1);
+    }
+    logger_1.logger.newline();
+    logger_1.logger.success(`Successfully updated to v${latestVersion}!`);
+}
+//# sourceMappingURL=update.js.map

package/dist/src/commands/update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../src/commands/update.ts"],"names":[],"mappings":"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"}

package/dist/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.5.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/src/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Auto-generated - do not edit
-exports.VERSION = "0.3.0";
+exports.VERSION = "0.5.0";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ketrics/ketrics-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "CLI tool for deploying applications to Ketrics platform",
   "main": "dist/index.js",
   "bin": {

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,19 +1,16 @@
 import { createAuthManager } from "@ketrics/sdk-frontend";
 
-const auth = createAuthManager();
-
-// Initialize auto-refresh
-auth.initAutoRefresh({
-  refreshBuffer: 60,
-  onTokenUpdated: () => {
-    // Token is refreshed automatically and retrieved via getAccessToken()
-  },
-});
+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;
   }
 
@@ -50,6 +47,27 @@ class APIClient {
   }
 }
 
-const apiClient = new APIClient(auth);
+// ---------------------------------------------------------------------------
+// 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 = await createClient();
 
 export { apiClient };

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

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