@ketrics/ketrics-cli 0.2.3 → 0.4.0

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",

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

@@ -11,23 +11,24 @@ body {
   min-height: 100vh;
   display: flex;
   justify-content: center;
-  align-items: center;
+  align-items: flex-start;
   padding: 20px;
 }
 
 .app {
   background: white;
   border-radius: 12px;
-  padding: 40px;
-  max-width: 500px;
+  padding: 32px;
+  max-width: 700px;
   width: 100%;
   box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+  margin-top: 20px;
 }
 
 h1 {
   color: #333;
-  margin-bottom: 8px;
-  font-size: 28px;
+  margin-bottom: 4px;
+  font-size: 26px;
 }
 
 .subtitle {
@@ -36,86 +37,110 @@ h1 {
   font-size: 14px;
 }
 
-.form {
+.sections {
   display: flex;
-  gap: 12px;
-  margin-bottom: 16px;
+  flex-direction: column;
+  gap: 20px;
 }
 
-.input {
-  flex: 1;
-  padding: 12px 16px;
-  border: 2px solid #e0e0e0;
-  border-radius: 8px;
-  font-size: 16px;
-  transition: border-color 0.2s;
+.section h2 {
+  font-size: 14px;
+  color: #555;
+  margin-bottom: 8px;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
 }
 
-.input:focus {
-  outline: none;
-  border-color: #667eea;
+.button-group {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
 }
 
 .button {
-  padding: 12px 24px;
+  padding: 8px 16px;
   background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
   color: white;
   border: none;
-  border-radius: 8px;
-  font-size: 16px;
-  font-weight: 600;
+  border-radius: 6px;
+  font-size: 13px;
+  font-weight: 500;
   cursor: pointer;
-  transition: transform 0.2s, box-shadow 0.2s;
+  transition: transform 0.15s, box-shadow 0.15s, opacity 0.15s;
 }
 
-.button:hover {
-  transform: translateY(-2px);
+.button:hover:not(:disabled) {
+  transform: translateY(-1px);
   box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
 }
 
-.button:active {
+.button:active:not(:disabled) {
   transform: translateY(0);
 }
 
+.button:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.loading {
+  color: #667eea;
+  font-weight: 500;
+  padding: 12px;
+  margin-top: 16px;
+}
+
 .error {
   color: #e53e3e;
   background: #fed7d7;
   padding: 12px;
   border-radius: 8px;
-  margin-bottom: 16px;
+  margin-top: 16px;
+  font-size: 14px;
 }
 
 .result {
-  color: #38a169;
-  background: #c6f6d5;
-  padding: 12px;
+  background: #f0fdf4;
+  border: 1px solid #bbf7d0;
   border-radius: 8px;
-  margin-bottom: 16px;
+  margin-top: 16px;
+  padding: 12px;
+  overflow-x: auto;
+}
+
+.result pre {
+  font-size: 12px;
+  color: #166534;
+  white-space: pre-wrap;
+  word-break: break-word;
+  margin: 0;
 }
 
 .info {
-  margin-top: 32px;
-  padding-top: 24px;
+  margin-top: 24px;
+  padding-top: 20px;
   border-top: 1px solid #e0e0e0;
 }
 
 .info h2 {
-  font-size: 18px;
+  font-size: 16px;
   color: #333;
-  margin-bottom: 12px;
+  margin-bottom: 8px;
 }
 
 .info p {
   color: #666;
-  margin-bottom: 12px;
+  margin-bottom: 8px;
   line-height: 1.5;
+  font-size: 14px;
 }
 
 .info ul {
   color: #666;
   padding-left: 20px;
+  font-size: 13px;
 }
 
 .info li {
-  margin-bottom: 6px;
+  margin-bottom: 4px;
 }