@ketrics/ketrics-cli 0.5.0 → 0.6.0

package/templates/HelloWorld/.claude/skills/ketrics-app/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: ketrics-app
+description: Scaffolds and builds Ketrics tenant applications with backend handlers, frontend React UI, and platform SDK integrations. Use when creating a new Ketrics app, adding backend handlers, setting up database connections, DocumentDB storage, Excel exports, Volume file storage, messaging, comments, environment variables, or deploying to the Ketrics platform.
+---
+
+# Ketrics Application Builder
+
+Build tenant applications on the Ketrics platform. This skill covers project scaffolding, backend handler development, frontend React integration, and deployment.
+
+## Architecture overview
+
+A Ketrics app has two parts:
+
+1. **Backend** (`backend/src/index.ts`): Single TypeScript file exporting async handler functions. Uses the global `ketrics` object (typed by `@ketrics/sdk-backend`) with no imports needed. Built with esbuild into a single bundle.
+2. **Frontend** (`frontend/src/`): React app (Vite + TypeScript) embedded as an iframe. Uses `@ketrics/sdk-frontend` for auth. Calls backend handlers via a service layer.
+
+A `ketrics.config.json` at the project root declares the app name, runtime, action names, entry point, and resources.
+
+## Project structure
+
+```
+my-ketrics-app/
+├── ketrics.config.json          # App config (actions, resources)
+├── CLAUDE.md                    # Dev instructions
+├── backend/
+│   ├── package.json             # devDeps: @ketrics/sdk-backend, esbuild, typescript
+│   ├── tsconfig.json
+│   └── src/
+│       └── index.ts             # All handler functions (single file)
+├── frontend/
+│   ├── package.json             # deps: react, @ketrics/sdk-frontend, vite
+│   ├── tsconfig.json
+│   ├── vite.config.ts
+│   ├── index.html
+│   └── src/
+│       ├── App.tsx              # Main component
+│       ├── main.tsx             # React entry point
+│       ├── types.ts             # Shared TypeScript interfaces
+│       ├── services/
+│       │   └── index.ts         # callFunction service layer
+│       └── mocks/
+│           └── handlers.ts      # Dev-mode mock handlers
+└── .github/
+    └── workflows/
+        └── deploy.yml           # CI/CD pipeline
+```
+
+## Step-by-step: Create a new app
+
+### 1. Initialize the project
+
+```bash
+mkdir my-ketrics-app && cd my-ketrics-app
+```
+
+### 2. Create `ketrics.config.json`
+
+```json
+{
+  "name": "my-ketrics-app",
+  "version": "1.0.0",
+  "description": "My Ketrics application",
+  "runtime": "nodejs18",
+  "actions": [
+    "listItems",
+    "getItem",
+    "createItem",
+    "updateItem",
+    "deleteItem"
+  ],
+  "entry": "dist/index.js",
+  "include": ["dist/**/*"],
+  "exclude": ["node_modules", "*.test.js"],
+  "resources": {
+    "documentdb": [
+      { "code": "app-data", "description": "Main data store" }
+    ]
+  }
+}
+```
+
+**Key rules:**
+- `actions` array MUST match the exported handler names in `backend/src/index.ts`
+- `resources` declares DocumentDB collections and Volumes the app needs
+- Add `"volume"` entries under resources when the app needs file storage
+
+### 3. Set up the backend
+
+```bash
+mkdir -p backend/src
+cd backend
+npm init -y
+npm install -D @ketrics/sdk-backend@0.11.0 esbuild typescript @types/node
+```
+
+**`backend/package.json` scripts:**
+```json
+{
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --target=es2020 --outfile=dist/index.js"
+  }
+}
+```
+
+### 4. Write backend handlers
+
+See [BACKEND_REFERENCE.md](BACKEND_REFERENCE.md) for the complete SDK API and patterns.
+
+Every handler is an `async` function that receives a typed payload and returns a result object:
+
+```typescript
+const myHandler = async (payload: { id: string }) => {
+  const userId = ketrics.requestor.userId;
+  // ... handler logic using ketrics.* SDK
+  return { result: "value" };
+};
+
+export { myHandler };
+```
+
+### 5. Set up the frontend
+
+```bash
+mkdir -p frontend/src/services frontend/src/mocks
+cd frontend
+npm init -y
+npm install react react-dom @ketrics/sdk-frontend
+npm install -D @vitejs/plugin-react vite typescript @types/react @types/react-dom
+```
+
+See [FRONTEND_REFERENCE.md](FRONTEND_REFERENCE.md) for the service layer, auth, and mock handler patterns.
+
+### 6. Deploy
+
+See [CONFIG_AND_DEPLOY.md](CONFIG_AND_DEPLOY.md) for ketrics.config.json details and GitHub Actions CI/CD.
+
+```bash
+# Manual deploy (requires .env with KETRICS_TOKEN)
+ketrics deploy --env .env
+```
+
+## SDK quick reference
+
+The `ketrics` global object is available in all backend handlers with no imports. Here's a quick overview of each subsystem:
+
+### Environment variables
+
+```typescript
+const value = ketrics.environment["MY_VAR"];
+```
+
+Read app-specific configuration. Common pattern: store JSON arrays for connection configs, resource codes, feature flags.
+
+### Requestor context
+
+```typescript
+ketrics.requestor.userId              // Current user ID
+ketrics.requestor.name                // Display name
+ketrics.requestor.email               // Email
+ketrics.requestor.applicationPermissions  // ["editor", ...]
+```
+
+### Database (SQL queries)
+
+```typescript
+const db = await ketrics.Database.connect(connectionCode);
+try {
+  const result = await db.query<Record<string, unknown>>(sql, params);
+  // result.rows, result.rowCount
+} finally {
+  await db.close();
+}
+```
+
+### DocumentDB (NoSQL storage)
+
+DynamoDB-style pk/sk model with `put`, `get`, `delete`, `list` operations.
+
+```typescript
+const docdb = await ketrics.DocumentDb.connect(resourceCode);
+await docdb.put(pk, sk, item);
+const item = await docdb.get(pk, sk);
+const result = await docdb.list(pk, { skPrefix: "PREFIX#" });
+await docdb.delete(pk, sk);
+```
+
+### Excel generation
+
+```typescript
+const excel = ketrics.Excel.create();
+const sheet = excel.addWorksheet("Sheet1");
+sheet.columns = columns.map(col => ({ header: col, key: col, width: 15 }));
+sheet.addRows(rows);
+const buffer = await excel.toBuffer();
+```
+
+### Volume (file storage)
+
+```typescript
+const volume = await ketrics.Volume.connect(volumeCode);
+await volume.put(fileKey, buffer);
+const { url } = await volume.generateDownloadUrl(fileKey);
+```
+
+### Messages (notifications)
+
+```typescript
+await ketrics.Messages.sendBulk({
+  userIds: ["user1", "user2"],
+  type: "CUSTOM_TYPE",
+  subject: "Subject line",
+  body: "**Markdown** body",
+  priority: "MEDIUM",
+});
+```
+
+### Users
+
+```typescript
+const users = await ketrics.Users.list();
+// [{ id, firstName, lastName, email }, ...]
+```
+
+### Logging
+
+```typescript
+ketrics.console.error("Non-critical error message");
+```
+
+### Application context
+
+```typescript
+ketrics.application.id  // Application UUID
+```
+
+## Common patterns
+
+### Permission checking
+
+```typescript
+function requireEditor(): void {
+  if (!ketrics.requestor.applicationPermissions.includes("editor")) {
+    throw new Error("Permission denied: editor role required");
+  }
+}
+```
+
+### Ownership verification
+
+```typescript
+const existing = await docdb.get(pk, sk);
+if (!existing) throw new Error("Not found");
+if (existing.createdBy !== userId) {
+  throw new Error("You can only modify your own resources");
+}
+```
+
+### DocumentDB key design
+
+Use prefixed composite keys for multi-entity storage in a single DocumentDB:
+
+| Entity | pk | sk |
+|--------|----|----|
+| User items | `USER#${userId}` | `ITEM#${itemId}` |
+| Tenant-wide | `TENANT_ITEMS` | `ITEM#${itemId}` |
+| Comments | `COMMENTS#${targetId}` | `COMMENT#${createdAt}#${commentId}` |
+| Index | `INDEX#${scope}` | `KEY#${lookupKey}` |
+
+### Export to Excel via Volume
+
+```typescript
+const exportToExcel = async (payload: { data: unknown[] }) => {
+  const volumeCode = ketrics.environment["EXPORTS_VOLUME"];
+  if (!volumeCode) throw new Error("EXPORTS_VOLUME not configured");
+
+  // Generate Excel
+  const excel = ketrics.Excel.create();
+  const sheet = excel.addWorksheet("Export");
+  // ... add columns and rows
+  const buffer = await excel.toBuffer();
+
+  // Save to Volume and get download URL
+  const filename = `export_${Date.now()}.xlsx`;
+  const fileKey = `${ketrics.application.id}/${filename}`;
+  const volume = await ketrics.Volume.connect(volumeCode);
+  await volume.put(fileKey, buffer);
+  const { url } = await volume.generateDownloadUrl(fileKey);
+
+  return { url, filename };
+};
+```
+
+### Comment system
+
+Store comments with composite keys for efficient queries. Use a separate index for fast count lookups:
+
+```typescript
+// Store comment
+await docdb.put(
+  `COMMENTS#${targetId}`,
+  `COMMENT#${createdAt}#${commentId}`,
+  commentData
+);
+
+// Update count index
+const indexItem = await docdb.get(`INDEX#${scope}`, `KEY#${targetId}`);
+const count = indexItem ? (indexItem.count as number) : 0;
+await docdb.put(`INDEX#${scope}`, `KEY#${targetId}`, {
+  targetId,
+  count: count + 1,
+  lastCommentAt: now,
+});
+```
+
+### Shared resources with access control
+
+```typescript
+// Filter: owned by me OR shared with me OR shared with all
+const items = result.items.filter((item) => {
+  if (item.owner === userId) return true;
+  if (item.visibility !== "shared") return false;
+  const sw = item.sharedWith;
+  if (sw === "all") return true;
+  if (Array.isArray(sw) && sw.includes(userId)) return true;
+  return false;
+});
+```
+
+## Additional resources
+
+- **Backend SDK reference**: See [BACKEND_REFERENCE.md](BACKEND_REFERENCE.md) for complete API docs and all handler patterns
+- **Frontend patterns**: See [FRONTEND_REFERENCE.md](FRONTEND_REFERENCE.md) for the service layer, auth manager, mock handlers, and type definitions
+- **Config and deployment**: See [CONFIG_AND_DEPLOY.md](CONFIG_AND_DEPLOY.md) for ketrics.config.json schema, GitHub Actions workflow, and environment setup
+
+## Checklist for new apps
+
+```
+- [ ] Create ketrics.config.json with correct actions and resources
+- [ ] Set up backend with @ketrics/sdk-backend and esbuild
+- [ ] Write handler functions using ketrics.* global
+- [ ] Export all handlers and sync with config actions array
+- [ ] Set up frontend with React, Vite, and @ketrics/sdk-frontend
+- [ ] Create callFunction service layer with dev/prod branching
+- [ ] Write mock handlers for local development
+- [ ] Define TypeScript interfaces in types.ts
+- [ ] Set up GitHub Actions deploy workflow
+- [ ] Configure environment variables in Ketrics dashboard
+```

package/templates/HelloWorld/.env.example

@@ -0,0 +1,20 @@
+# Ketrics Deployment Configuration
+# Copy this file to .env and fill in your values
+
+# API URL (default for production)
+KETRICS_API_URL=https://api.ketrics.io/api/v1
+
+# RUNTIME API URL (default for production)
+KETRICS_RUNTIME_URL=https://runtime.ketrics.io
+
+# Your tenant ID
+KETRICS_TENANT_ID=TENANT_ID_HERE
+
+# Application ID for this backend
+KETRICS_APPLICATION_ID=APPLICATION_ID_HERE
+
+# Deployment token from Ketrics dashboard
+KETRICS_TOKEN=KETRICS_TOKEN_HERE
+
+# Optional: Custom authentication token (JWT) for Ketrics API
+KETRICS_AUTH_TOKEN=KETRICS_AUTH_TOKEN_HERE

package/templates/HelloWorld/.github/workflows/deploy.yml

@@ -0,0 +1,51 @@
+name: Deploy to Ketrics
+
+on:
+  push:
+    branches: [master]
+
+env:
+  KETRICS_API_URL: https://api.ketrics.io/api/v1
+  KETRICS_RUNTIME_URL: https://runtime.ketrics.io
+  KETRICS_TENANT_ID: KETRICS_TENANT_ID
+  KETRICS_APPLICATION_ID: KETRICS_APPLICATION_ID
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: prod
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+
+      # Install Ketrics CLI
+      - run: npm install -g @ketrics/ketrics-cli
+
+      # Generate .env file (only KETRICS_TOKEN is a secret)
+      - name: Generate .env file
+        run: |
+          cat <<EOF > .env
+          KETRICS_API_URL=$KETRICS_API_URL
+          KETRICS_RUNTIME_URL=$KETRICS_RUNTIME_URL
+          KETRICS_TENANT_ID=$KETRICS_TENANT_ID
+          KETRICS_APPLICATION_ID=$KETRICS_APPLICATION_ID
+          KETRICS_TOKEN=${{ secrets.KETRICS_TOKEN }}
+          EOF
+
+      # Backend: install + build
+      - run: npm ci
+        working-directory: backend
+      - run: npm run build
+        working-directory: backend
+
+      # Frontend: install + build
+      - run: npm ci
+        working-directory: frontend
+      - run: npm run build
+        working-directory: frontend
+
+      # Deploy
+      - run: ketrics deploy --env .env

package/templates/HelloWorld/backend/package.json

@@ -9,7 +9,7 @@
     "clean": "rm -rf dist"
   },
   "devDependencies": {
-    "@ketrics/sdk-backend": "0.8.0",
+    "@ketrics/sdk-backend": "0.11.0",
     "@types/node": ">=24.0.0",
     "esbuild": "^0.27.2",
     "ts-node": "^1.7.1",