@ketrics/ketrics-cli 0.2.2 → 0.3.0

package/templates/HelloWorld/backend/src/index.ts

@@ -1,57 +1,133 @@
 /**
  * Ketrics Application Backend
  *
- * Exports handler functions compatible with Ketrics data-plane-api.
+ * Exports handler functions compatible with Ketrics Runtime API.
  *
- * The `ketrics` global object is automatically typed via @ketrics/sdk.
+ * The `ketrics` global object is automatically typed via @ketrics/sdk-backend.
  * No imports needed - just use `ketrics.*` directly.
  *
  * Available SDK features:
- * - ketrics.tenant, ketrics.application, ketrics.requestor, ketrics.env (context)
+ * - ketrics.tenant, ketrics.application, ketrics.requestor, ketrics.runtime, ketrics.environment (context)
  * - ketrics.console (logging to CloudWatch)
  * - ketrics.http (HTTP client for external APIs)
- * - ketrics.Volume.connect(code) (S3-backed storage)
- * - ketrics.DatabaseConnection.connect(code) (external databases)
+ * - ketrics.Volume.connect(code) (S3-backed file storage)
+ * - ketrics.Database.connect(code) (external SQL databases)
  * - ketrics.Secret.get(code) (encrypted secrets)
+ * - ketrics.Excel.create() / ketrics.Excel.read(buffer) (Excel workbooks)
+ * - ketrics.Pdf.create() / ketrics.Pdf.read(buffer) (PDF documents)
+ * - ketrics.Job.runInBackground(params) (background job execution)
+ * - ketrics.Messages.send(params) (user messaging)
  */
 
+// Volume examples: save, read, list, download URL, copy files
+import {
+  saveFile,
+  readFile,
+  listFiles,
+  generateDownloadUrl,
+  copyFile,
+} from "./volumes";
+
+// Database examples: query, insert, transaction
+import {
+  queryUsers,
+  insertRecord,
+  transferFunds,
+} from "./database";
+
+// PDF examples: create invoice, create report
+import {
+  createInvoicePdf,
+  createSimplePdf,
+} from "./pdf";
+
+// Excel examples: create spreadsheet, export data
+import {
+  createSpreadsheet,
+  exportDataToExcel,
+} from "./excel";
+
+// Secret management examples
+import { getSecret } from "./secrets";
+
+// Messaging examples
+import { sendNotification, sendBulkNotification } from "./messages";
+
+// Background job examples
+import { scheduleBackgroundJob, getJobStatus } from "./jobs";
+
+// HTTP client examples
+import { fetchExternalApi } from "./http";
+
 // ============================================================================
 // Basic Handlers
 // ============================================================================
 
-import { saveFile, readFile, generateDownloadUrl, testWriteFileWithoutVolumeGrant } from "./volume";
-import { getSecret, getSecretWithoutGrant } from "./secrets";
-
 /**
- * Echo handler - returns payload with context info
- *
- * @param payload - Any payload to echo back
- * @returns Payload with additional context information
+ * Echo handler - returns the payload along with full context info.
+ * Useful for debugging and verifying SDK access.
  */
-
 const echo = async (payload: unknown) => {
   ketrics.console.log(
-    `Echo was called by ${ketrics.requestor.type}:${ketrics.requestor.userId || ketrics.requestor.serviceAccountCode} in tenant ${ketrics.tenant.id}`,
+    `Echo called by ${ketrics.requestor.type}:${ketrics.requestor.userId || ketrics.requestor.serviceAccountCode}`,
   );
 
-  // Only send message if requestor is a user
-
-  if (ketrics.requestor.type === "USER") {
-    await ketrics.Messages.send({
-      userId: ketrics.requestor.userId!,
-      type: "notification",
-      subject: "Echo called",
-      body: `Echo was called by ${ketrics.requestor.type}:${ketrics.requestor.email} in tenant ${ketrics.tenant.id}`,
-    });
-  }
+  return {
+    payload,
+    context: {
+      tenant: ketrics.tenant,
+      application: ketrics.application,
+      requestor: ketrics.requestor,
+      runtime: ketrics.runtime,
+      environment: ketrics.environment,
+    },
+  };
+};
 
+/**
+ * Info handler - returns runtime environment details.
+ */
+const info = async () => {
   return {
-    tenant: ketrics.tenant,
-    requestor: ketrics.requestor,
-    application: ketrics.application,
-    environment: ketrics.environment,
+    tenant: { id: ketrics.tenant.id, code: ketrics.tenant.code, name: ketrics.tenant.name },
+    application: {
+      id: ketrics.application.id,
+      code: ketrics.application.code,
+      name: ketrics.application.name,
+      version: ketrics.application.version,
+    },
     runtime: ketrics.runtime,
   };
 };
 
-export { echo, saveFile, readFile, generateDownloadUrl, testWriteFileWithoutVolumeGrant, getSecret, getSecretWithoutGrant };
+export {
+  // Basic
+  echo,
+  info,
+  // Volumes
+  saveFile,
+  readFile,
+  listFiles,
+  generateDownloadUrl,
+  copyFile,
+  // Database
+  queryUsers,
+  insertRecord,
+  transferFunds,
+  // PDF
+  createInvoicePdf,
+  createSimplePdf,
+  // Excel
+  createSpreadsheet,
+  exportDataToExcel,
+  // Secrets
+  getSecret,
+  // Messages
+  sendNotification,
+  sendBulkNotification,
+  // Jobs
+  scheduleBackgroundJob,
+  getJobStatus,
+  // HTTP
+  fetchExternalApi,
+};

package/templates/HelloWorld/backend/src/jobs.ts

@@ -0,0 +1,47 @@
+/**
+ * Background Job Examples
+ *
+ * Demonstrates scheduling and monitoring background jobs using ketrics.Job.
+ * Background jobs run asynchronously and can have longer timeouts (up to 15 minutes).
+ */
+
+/**
+ * Schedule a function to run in the background.
+ */
+const scheduleBackgroundJob = async (payload: {
+  functionName?: string;
+  data?: Record<string, unknown>;
+}) => {
+  const jobId = await ketrics.Job.runInBackground({
+    function: payload?.functionName || "echo",
+    payload: payload?.data || { source: "background-job" },
+    options: {
+      timeout: 60000, // 1 minute timeout
+    },
+  });
+
+  return { jobId, status: "scheduled" };
+};
+
+/**
+ * Check the status of a background job.
+ */
+const getJobStatus = async (payload: { jobId: string }) => {
+  if (!payload?.jobId) {
+    throw new Error("jobId is required");
+  }
+
+  const status = await ketrics.Job.getStatus(payload.jobId);
+
+  return {
+    jobId: status.jobId,
+    functionName: status.functionName,
+    status: status.status,
+    createdAt: status.createdAt,
+    startedAt: status.startedAt,
+    completedAt: status.completedAt,
+    error: status.error,
+  };
+};
+
+export { scheduleBackgroundJob, getJobStatus };

package/templates/HelloWorld/backend/src/messages.ts

@@ -0,0 +1,59 @@
+/**
+ * Messages Examples
+ *
+ * Demonstrates sending notifications to users via ketrics.Messages.
+ * Messages appear in the user's inbox within the Ketrics portal.
+ */
+
+/**
+ * Send a notification to the current user.
+ */
+const sendNotification = async (payload: { subject?: string; body?: string }) => {
+  if (ketrics.requestor.type !== "USER") {
+    throw new Error("This function can only be called by a user");
+  }
+
+  const result = await ketrics.Messages.send({
+    userId: ketrics.requestor.userId!,
+    type: "notification",
+    subject: payload?.subject || "Hello from your app!",
+    body: payload?.body || `This notification was sent by **${ketrics.application.name}**.`,
+    priority: "MEDIUM",
+    channels: { inbox: true, push: false },
+  });
+
+  return {
+    messageId: result.messageId,
+    status: result.status,
+  };
+};
+
+/**
+ * Send a notification to multiple users.
+ */
+const sendBulkNotification = async (payload: {
+  userIds: string[];
+  subject: string;
+  body: string;
+}) => {
+  if (!payload?.userIds?.length) {
+    throw new Error("userIds array is required");
+  }
+
+  const result = await ketrics.Messages.sendBulk({
+    userIds: payload.userIds,
+    type: "announcement",
+    subject: payload.subject,
+    body: payload.body,
+    priority: "HIGH",
+    channels: { inbox: true, push: true },
+  });
+
+  return {
+    total: result.total,
+    sent: result.sent,
+    failed: result.failed,
+  };
+};
+
+export { sendNotification, sendBulkNotification };

package/templates/HelloWorld/backend/src/pdf.ts

@@ -0,0 +1,212 @@
+/**
+ * PDF Examples
+ *
+ * Demonstrates PDF document creation using ketrics.Pdf.
+ * Generated PDFs can be saved to a volume for download.
+ */
+
+/**
+ * Create a simple PDF document and save it to a volume.
+ */
+const createSimplePdf = async () => {
+  const doc = await ketrics.Pdf.create();
+
+  // Set document metadata
+  doc.setTitle("Sample Document");
+  doc.setAuthor(ketrics.tenant.name);
+  doc.setCreator(ketrics.application.name);
+
+  // Add a page
+  const page = doc.addPage({ size: "A4" });
+
+  // Embed a standard font
+  const font = await doc.embedStandardFont("Helvetica");
+  const boldFont = await doc.embedStandardFont("Helvetica-Bold");
+
+  // Draw title
+  page.drawText("Hello from Ketrics!", {
+    x: 50,
+    y: 780,
+    size: 28,
+    font: boldFont,
+    color: ketrics.Pdf.rgb(0.2, 0.2, 0.6),
+  });
+
+  // Draw subtitle
+  page.drawText(`Generated by ${ketrics.application.name} for ${ketrics.tenant.name}`, {
+    x: 50,
+    y: 750,
+    size: 12,
+    font,
+    color: ketrics.Pdf.rgb(0.4, 0.4, 0.4),
+  });
+
+  // Draw a decorative line
+  page.drawLine({
+    start: { x: 50, y: 740 },
+    end: { x: 545, y: 740 },
+    thickness: 2,
+    color: ketrics.Pdf.rgb(0.2, 0.2, 0.6),
+  });
+
+  // Draw body text
+  page.drawText("This PDF was generated dynamically using the Ketrics PDF SDK.", {
+    x: 50,
+    y: 710,
+    size: 14,
+    font,
+    color: ketrics.Pdf.rgb(0, 0, 0),
+  });
+
+  page.drawText(`Date: ${new Date().toISOString()}`, {
+    x: 50,
+    y: 685,
+    size: 11,
+    font,
+    color: ketrics.Pdf.rgb(0.3, 0.3, 0.3),
+  });
+
+  // Save to volume
+  const buffer = await doc.toBuffer();
+  const volume = await ketrics.Volume.connect("test-volume");
+  const result = await volume.put("documents/sample.pdf", buffer, {
+    contentType: "application/pdf",
+  });
+
+  // Generate download URL
+  const downloadUrl = await volume.generateDownloadUrl("documents/sample.pdf", {
+    expiresIn: 3600,
+  });
+
+  return {
+    file: { key: result.key, size: result.size },
+    downloadUrl: downloadUrl.url,
+    pageCount: doc.getPageCount(),
+  };
+};
+
+/**
+ * Create an invoice-style PDF with structured data.
+ */
+const createInvoicePdf = async (payload: {
+  invoiceNumber?: string;
+  customerName?: string;
+  items?: Array<{ description: string; quantity: number; price: number }>;
+}) => {
+  const invoiceNumber = payload?.invoiceNumber || "INV-001";
+  const customerName = payload?.customerName || "Sample Customer";
+  const items = payload?.items || [
+    { description: "Web Development", quantity: 40, price: 150 },
+    { description: "Design Services", quantity: 20, price: 120 },
+    { description: "Consulting", quantity: 10, price: 200 },
+  ];
+
+  const doc = await ketrics.Pdf.create();
+  doc.setTitle(`Invoice ${invoiceNumber}`);
+  doc.setAuthor(ketrics.tenant.name);
+
+  const page = doc.addPage({ size: "A4" });
+  const font = await doc.embedStandardFont("Helvetica");
+  const boldFont = await doc.embedStandardFont("Helvetica-Bold");
+
+  let y = 780;
+
+  // Header
+  page.drawText("INVOICE", {
+    x: 50, y, size: 32, font: boldFont,
+    color: ketrics.Pdf.rgb(0.2, 0.2, 0.6),
+  });
+
+  y -= 35;
+  page.drawText(`#${invoiceNumber}`, {
+    x: 50, y, size: 14, font,
+    color: ketrics.Pdf.rgb(0.4, 0.4, 0.4),
+  });
+
+  // Company info (right side)
+  page.drawText(ketrics.tenant.name, {
+    x: 400, y: 780, size: 14, font: boldFont,
+    color: ketrics.Pdf.rgb(0, 0, 0),
+  });
+
+  page.drawText(new Date().toLocaleDateString(), {
+    x: 400, y: 762, size: 11, font,
+    color: ketrics.Pdf.rgb(0.4, 0.4, 0.4),
+  });
+
+  // Divider
+  y -= 20;
+  page.drawLine({
+    start: { x: 50, y },
+    end: { x: 545, y },
+    thickness: 1,
+    color: ketrics.Pdf.rgb(0.8, 0.8, 0.8),
+  });
+
+  // Bill To
+  y -= 30;
+  page.drawText("Bill To:", { x: 50, y, size: 10, font, color: ketrics.Pdf.rgb(0.5, 0.5, 0.5) });
+  y -= 18;
+  page.drawText(customerName, { x: 50, y, size: 14, font: boldFont, color: ketrics.Pdf.rgb(0, 0, 0) });
+
+  // Table header
+  y -= 40;
+  page.drawRectangle({
+    x: 50, y: y - 5, width: 495, height: 25,
+    color: ketrics.Pdf.rgb(0.93, 0.93, 0.97),
+  });
+
+  page.drawText("Description", { x: 60, y, size: 10, font: boldFont, color: ketrics.Pdf.rgb(0.3, 0.3, 0.3) });
+  page.drawText("Qty", { x: 330, y, size: 10, font: boldFont, color: ketrics.Pdf.rgb(0.3, 0.3, 0.3) });
+  page.drawText("Price", { x: 400, y, size: 10, font: boldFont, color: ketrics.Pdf.rgb(0.3, 0.3, 0.3) });
+  page.drawText("Total", { x: 480, y, size: 10, font: boldFont, color: ketrics.Pdf.rgb(0.3, 0.3, 0.3) });
+
+  // Table rows
+  let grandTotal = 0;
+  for (const item of items) {
+    y -= 25;
+    const lineTotal = item.quantity * item.price;
+    grandTotal += lineTotal;
+
+    page.drawText(item.description, { x: 60, y, size: 11, font, color: ketrics.Pdf.rgb(0, 0, 0) });
+    page.drawText(String(item.quantity), { x: 335, y, size: 11, font, color: ketrics.Pdf.rgb(0, 0, 0) });
+    page.drawText(`$${item.price.toFixed(2)}`, { x: 395, y, size: 11, font, color: ketrics.Pdf.rgb(0, 0, 0) });
+    page.drawText(`$${lineTotal.toFixed(2)}`, { x: 475, y, size: 11, font, color: ketrics.Pdf.rgb(0, 0, 0) });
+  }
+
+  // Total
+  y -= 15;
+  page.drawLine({
+    start: { x: 380, y },
+    end: { x: 545, y },
+    thickness: 1,
+    color: ketrics.Pdf.rgb(0.8, 0.8, 0.8),
+  });
+
+  y -= 20;
+  page.drawText("Total:", { x: 400, y, size: 14, font: boldFont, color: ketrics.Pdf.rgb(0, 0, 0) });
+  page.drawText(`$${grandTotal.toFixed(2)}`, {
+    x: 470, y, size: 14, font: boldFont,
+    color: ketrics.Pdf.rgb(0.2, 0.2, 0.6),
+  });
+
+  // Save to volume
+  const buffer = await doc.toBuffer();
+  const volume = await ketrics.Volume.connect("test-volume");
+  const fileName = `invoices/${invoiceNumber}.pdf`;
+  const result = await volume.put(fileName, buffer, {
+    contentType: "application/pdf",
+  });
+
+  const downloadUrl = await volume.generateDownloadUrl(fileName, { expiresIn: 3600 });
+
+  return {
+    file: { key: result.key, size: result.size },
+    downloadUrl: downloadUrl.url,
+    invoiceNumber,
+    total: grandTotal,
+    itemCount: items.length,
+  };
+};
+
+export { createSimplePdf, createInvoicePdf };

package/templates/HelloWorld/backend/src/secrets.ts

@@ -1,17 +1,24 @@
-const getSecret = async (key: string): Promise<{ value: string }> => {
-  const value = await ketrics.Secret.get("apikey");
-  if (!value) {
-    throw new Error(`Secret with key "${key}" not found`);
-  }
-  return { value };
-};
+/**
+ * Secret Examples
+ *
+ * Demonstrates encrypted secret retrieval using ketrics.Secret.
+ * Secrets must be created and granted to the application in the Ketrics portal.
+ */
+
+/**
+ * Retrieve an encrypted secret by code.
+ */
+const getSecret = async (payload: { code?: string }) => {
+  const secretCode = payload?.code || "apikey";
+  const value = await ketrics.Secret.get(secretCode);
 
-const getSecretWithoutGrant = async (key: string): Promise<{ value: string }> => {
-  const value = await ketrics.Secret.get("missing-grant-secret");
-  if (!value) {
-    throw new Error(`Secret with key "${key}" not found`);
-  }
-  return { value };
+  // In production, never return the secret value directly.
+  // This is only for demonstration purposes.
+  return {
+    code: secretCode,
+    retrieved: true,
+    valueLength: value.length,
+  };
 };
 
-export { getSecret, getSecretWithoutGrant };
+export { getSecret };

package/templates/HelloWorld/backend/src/volumes.ts

@@ -0,0 +1,107 @@
+/**
+ * Volume Examples
+ *
+ * Demonstrates S3-backed file storage operations using ketrics.Volume.
+ * Volumes must be granted to the application in the Ketrics portal before use.
+ */
+
+/**
+ * Save files to a volume - demonstrates writing JSON and binary data.
+ */
+const saveFile = async () => {
+  const volume = await ketrics.Volume.connect("test-volume");
+
+  // Write JSON content
+  const jsonData = {
+    generatedBy: ketrics.application.code,
+    generatedAt: new Date().toISOString(),
+    tenant: ketrics.tenant.code,
+  };
+  const jsonResult = await volume.put("output/data.json", JSON.stringify(jsonData), {
+    contentType: "application/json",
+  });
+
+  // Write plain text content
+  const textResult = await volume.put("output/hello.txt", Buffer.from("Hello from Ketrics!"), {
+    contentType: "text/plain",
+  });
+
+  return {
+    jsonFile: { key: jsonResult.key, etag: jsonResult.etag, size: jsonResult.size },
+    textFile: { key: textResult.key, etag: textResult.etag, size: textResult.size },
+  };
+};
+
+/**
+ * Read a file from a volume - demonstrates reading and parsing stored data.
+ */
+const readFile = async () => {
+  const volume = await ketrics.Volume.connect("test-volume");
+
+  const exists = await volume.exists("output/data.json");
+  if (!exists) {
+    return { error: "File not found. Run saveFile first." };
+  }
+
+  const file = await volume.get("output/data.json");
+  const content = file.content.toString();
+
+  return {
+    contentType: file.contentType,
+    contentLength: file.contentLength,
+    lastModified: file.lastModified,
+    parsed: JSON.parse(content),
+  };
+};
+
+/**
+ * List files in a volume - demonstrates pagination and prefix filtering.
+ */
+const listFiles = async (payload: { prefix?: string }) => {
+  const volume = await ketrics.Volume.connect("test-volume");
+
+  const result = await volume.list({
+    prefix: payload?.prefix || "output/",
+    maxResults: 50,
+  });
+
+  return {
+    files: result.files.map((f) => ({
+      key: f.key,
+      size: f.size,
+      lastModified: f.lastModified,
+      contentType: f.contentType,
+    })),
+    count: result.count,
+    isTruncated: result.isTruncated,
+  };
+};
+
+/**
+ * Generate a temporary download URL for a file.
+ */
+const generateDownloadUrl = async () => {
+  const volume = await ketrics.Volume.connect("test-volume");
+  const result = await volume.generateDownloadUrl("output/data.json", {
+    expiresIn: 3600, // 1 hour
+  });
+
+  return { url: result.url, expiresAt: result.expiresAt };
+};
+
+/**
+ * Copy a file within a volume.
+ */
+const copyFile = async () => {
+  const volume = await ketrics.Volume.connect("test-volume");
+
+  const result = await volume.copy("output/data.json", "backup/data-backup.json");
+
+  return {
+    sourceKey: result.sourceKey,
+    destinationKey: result.destinationKey,
+    etag: result.etag,
+  };
+};
+
+export { saveFile, readFile, listFiles, generateDownloadUrl, copyFile };

package/templates/HelloWorld/frontend/package.json

@@ -9,10 +9,8 @@
   },
   "dependencies": {
     "@ketrics/sdk-frontend": "^0.1.1",
-    "axios": "^1.13.2",
     "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "zod": "^3.22.4"
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
     "@types/react": "^18.2.0",