@paralect/hive 0.1.48 → 0.1.50-alpha.0

package/starter/.cursor/commands/add-middleware.md

@@ -0,0 +1,95 @@
+# Add Middleware
+
+Creates a new middleware for endpoints.
+
+## Command Format
+
+```
+add-middleware {name}
+```
+
+**Examples:**
+- `add-middleware isAdmin`
+- `add-middleware canEditProject`
+- `add-middleware rateLimit`
+
+## Location
+
+`src/middlewares/{name}.js`
+
+## Template (simple)
+
+```javascript
+export default async (ctx, next) => {
+  // Middleware logic here
+  
+  return next();
+};
+```
+
+## Template (with parameters)
+
+```javascript
+export default (param) => async (ctx, next) => {
+  // Use param here
+  
+  return next();
+};
+```
+
+## Examples
+
+### Access control
+
+```javascript
+export default async (ctx, next) => {
+  if (!ctx.state.user?.isAdmin) {
+    ctx.throw(403, 'Admin access required');
+  }
+  
+  return next();
+};
+```
+
+### With parameters
+
+```javascript
+import db from 'db';
+
+export default (resource, getId = (ctx) => ctx.params.id) => async (ctx, next) => {
+  const id = getId(ctx);
+  const doc = await db.services[resource].findOne({ _id: id });
+  
+  if (!doc) {
+    ctx.throw(404, `${resource} not found`);
+  }
+  
+  ctx.state[resource] = doc;
+  return next();
+};
+```
+
+### With runOrder (lower runs first)
+
+```javascript
+const middleware = async (ctx, next) => {
+  ctx.state.isSkipAuth = true;
+  return next();
+};
+
+middleware.runOrder = -1;
+
+export default middleware;
+```
+
+## Usage in endpoints
+
+```javascript
+// Import and use directly
+import isAdmin from 'middlewares/isAdmin';
+export const middlewares = [isAdmin];
+
+// With parameters
+import canEdit from 'middlewares/canEdit';
+export const middlewares = [canEdit('projects', (ctx) => ctx.params.projectId)];
+```

package/starter/.cursor/commands/add-resource.md

@@ -0,0 +1,71 @@
+# Add Resource
+
+Creates a complete resource with schema and folder structure.
+
+## Steps
+
+1. Create folder: `src/resources/{name}/`
+2. Create schema file: `src/resources/{name}/{name}.schema.js`
+3. Create folders: `endpoints/`, `handlers/`, `methods/`
+4. Create first endpoint: `src/resources/{name}/endpoints/list.js`
+
+## Schema Template
+
+**File:** `src/resources/{name}/{name}.schema.js`
+
+```javascript
+import { z } from 'zod';
+import dbSchema from 'helpers/schema/db.schema.js';
+
+const schema = dbSchema.extend({
+  // Add fields here
+  title: z.coerce.string().nullable().optional(),
+});
+
+export default schema;
+
+export const secureFields = [];
+```
+
+## First Endpoint Template
+
+**File:** `src/resources/{name}/endpoints/list.js`
+
+```javascript
+import { z } from 'zod';
+import db from 'db';
+
+const {name}Service = db.services.{name};
+
+export const middlewares = [];
+
+export const requestSchema = z.object({
+  page: z.coerce.number().default(1),
+  perPage: z.coerce.number().default(20),
+});
+
+export const handler = async (ctx) => {
+  const { page, perPage } = ctx.validatedData;
+
+  return {name}Service.find(
+    {},
+    { page, perPage, sort: '-createdOn' }
+  );
+};
+
+export const endpoint = {
+  url: '/',
+  method: 'get',
+};
+```
+
+## Result
+
+```
+src/resources/{name}/
+├── {name}.schema.js
+├── endpoints/
+│   └── list.js
+├── handlers/
+└── methods/
+```

package/starter/.cursor/commands/add-scheduler.md

@@ -0,0 +1,138 @@
+# Add Scheduler
+
+Creates a new scheduled background job.
+
+## Command Format
+
+```
+add-scheduler {name} [{schedule}]
+```
+
+**Examples:**
+- `add-scheduler syncExternalData every 5 minutes`
+- `add-scheduler sendDailyReport daily at 9am`
+- `add-scheduler markOverdueInvoices every day at midnight`
+- `add-scheduler weeklyCleanup every monday at 3am`
+
+## Schedule to Cron
+
+Translate natural language to cron:
+
+| User says | Cron |
+|-----------|------|
+| every minute | `* * * * *` |
+| every 5 minutes | `*/5 * * * *` |
+| every hour | `0 * * * *` |
+| every 6 hours | `0 */6 * * *` |
+| daily at midnight | `0 0 * * *` |
+| daily at 9am | `0 9 * * *` |
+| every monday at 9am | `0 9 * * 1` |
+| first of month | `0 0 1 * *` |
+
+## Location
+
+`src/scheduler/handlers/{name}.js`
+
+## Template
+
+```javascript
+import db from 'db';
+
+export const handler = async () => {
+  // Job logic here
+};
+
+export const cron = '0 * * * *'; // Every hour
+```
+
+## Examples
+
+### Sync external data
+
+```javascript
+import db from 'db';
+import moment from 'moment';
+import externalApi from 'services/externalApi';
+
+const itemsService = db.services.items;
+
+export const handler = async () => {
+  const items = await externalApi.list({
+    updatedSince: moment().subtract(5, 'minutes').toDate(),
+  });
+
+  for (const item of items) {
+    await itemsService.updateOne(
+      { externalId: item.id },
+      (doc) => ({ ...doc, ...item })
+    );
+  }
+};
+
+export const cron = '*/5 * * * *';
+```
+
+### Send daily report
+
+```javascript
+import db from 'db';
+import slack from 'services/slack';
+
+const tasksService = db.services.tasks;
+
+export const handler = async () => {
+  const { count: completed } = await tasksService.find({ status: 'completed' });
+  const { count: pending } = await tasksService.find({ status: 'pending' });
+
+  await slack.sendChannelMessage({
+    channel: '#reports',
+    text: `Daily report: ${completed} completed, ${pending} pending`,
+  });
+};
+
+export const cron = '0 9 * * *';
+```
+
+### Mark overdue invoices
+
+```javascript
+import db from 'db';
+
+const invoicesService = db.services.invoices;
+
+export const handler = async () => {
+  await invoicesService.updateMany(
+    {
+      isPaid: { $ne: true },
+      isOverdue: { $ne: true },
+      dueOn: { $lt: new Date() },
+    },
+    (doc) => ({ ...doc, isOverdue: true })
+  );
+};
+
+export const cron = '0 0 * * *';
+```
+
+### Cleanup old records
+
+```javascript
+import db from 'db';
+import moment from 'moment';
+
+const logsService = db.services.logs;
+
+export const handler = async () => {
+  await logsService.remove({
+    createdOn: { $lt: moment().subtract(30, 'days').toDate() },
+  });
+};
+
+export const cron = '0 3 * * *';
+```
+
+## Tips
+
+- Keep jobs idempotent (safe to re-run)
+- Log progress for debugging
+- Use `atomic.update` for bulk operations

package/starter/.cursor/commands/add-service.md

@@ -0,0 +1,188 @@
+# Add Service
+
+Creates a new service for external APIs or utilities.
+
+## Command Format
+
+```
+add-service {name} [{methods}]
+```
+
+**Examples:**
+- `add-service slack sendChannelMessage, replyToThread`
+- `add-service stripe createCustomer, createPaymentIntent, listInvoices`
+- `add-service openai chat, generateImage`
+- `add-service sendgrid sendEmail, sendTemplateEmail`
+
+## Location
+
+`src/services/{name}.js`
+
+## Known Services & Libraries
+
+When creating a service, use these go-to libraries:
+
+| Service | Library | Install |
+|---------|---------|---------|
+| Slack | `@slack/web-api` | `npm i @slack/web-api` |
+| Stripe | `stripe` | `npm i stripe` |
+| OpenAI | `openai` | `npm i openai` |
+| SendGrid | `@sendgrid/mail` | `npm i @sendgrid/mail` |
+| Twilio | `twilio` | `npm i twilio` |
+| AWS S3 | `@aws-sdk/client-s3` | `npm i @aws-sdk/client-s3` |
+| Resend | `resend` | `npm i resend` |
+| Postmark | `postmark` | `npm i postmark` |
+
+## Template
+
+```javascript
+import config from 'app-config';
+
+// Initialize client here
+
+export default {
+  client,
+
+  // Methods here
+};
+```
+
+## Full Examples
+
+### `add-service slack sendChannelMessage, replyToThread`
+
+```javascript
+import config from 'app-config';
+import { WebClient } from '@slack/web-api';
+
+const client = new WebClient(config.slack.botToken);
+
+export default {
+  client,
+
+  sendChannelMessage: async ({ channel, text, blocks }) => {
+    return client.chat.postMessage({ channel, text, blocks });
+  },
+
+  replyToThread: async ({ channel, threadTs, text }) => {
+    return client.chat.postMessage({ channel, text, thread_ts: threadTs });
+  },
+};
+```
+
+### `add-service stripe createCustomer, createPaymentIntent, listInvoices`
+
+```javascript
+import config from 'app-config';
+import Stripe from 'stripe';
+
+const client = new Stripe(config.stripe.secretKey);
+
+export default {
+  client,
+
+  createCustomer: async ({ email, name, metadata }) => {
+    return client.customers.create({ email, name, metadata });
+  },
+
+  createPaymentIntent: async ({ amount, currency, customerId }) => {
+    return client.paymentIntents.create({
+      amount,
+      currency,
+      customer: customerId,
+    });
+  },
+
+  listInvoices: async ({ customerId, limit = 10 }) => {
+    return client.invoices.list({ customer: customerId, limit });
+  },
+};
+```
+
+### `add-service openai chat, generateImage`
+
+```javascript
+import config from 'app-config';
+import OpenAI from 'openai';
+
+const client = new OpenAI({ apiKey: config.openai.apiKey });
+
+export default {
+  client,
+
+  chat: async ({ messages, model = 'gpt-4' }) => {
+    const response = await client.chat.completions.create({ model, messages });
+    return response.choices[0].message;
+  },
+
+  generateImage: async ({ prompt, size = '1024x1024' }) => {
+    const response = await client.images.generate({ prompt, size, n: 1 });
+    return response.data[0].url;
+  },
+};
+```
+
+### `add-service sendgrid sendEmail, sendTemplateEmail`
+
+```javascript
+import config from 'app-config';
+import sgMail from '@sendgrid/mail';
+
+sgMail.setApiKey(config.sendgrid.apiKey);
+
+export default {
+  sendEmail: async ({ to, from, subject, html }) => {
+    return sgMail.send({ to, from, subject, html });
+  },
+
+  sendTemplateEmail: async ({ to, from, templateId, dynamicTemplateData }) => {
+    return sgMail.send({ to, from, templateId, dynamicTemplateData });
+  },
+};
+```
+
+### `add-service s3 upload, getSignedUrl, delete`
+
+```javascript
+import config from 'app-config';
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+
+const client = new S3Client({
+  region: config.aws.region,
+  credentials: {
+    accessKeyId: config.aws.accessKeyId,
+    secretAccessKey: config.aws.secretAccessKey,
+  },
+});
+
+export default {
+  client,
+
+  upload: async ({ bucket, key, body, contentType }) => {
+    const command = new PutObjectCommand({ Bucket: bucket, Key: key, Body: body, ContentType: contentType });
+    return client.send(command);
+  },
+
+  getSignedUrl: async ({ bucket, key, expiresIn = 3600 }) => {
+    const command = new GetObjectCommand({ Bucket: bucket, Key: key });
+    return getSignedUrl(client, command, { expiresIn });
+  },
+
+  delete: async ({ bucket, key }) => {
+    const command = new DeleteObjectCommand({ Bucket: bucket, Key: key });
+    return client.send(command);
+  },
+};
+```
+
+## Usage
+
+```javascript
+import slack from 'services/slack';
+import stripe from 'services/stripe';
+
+await slack.sendChannelMessage({ channel: '#general', text: 'Hello' });
+
+const customer = await stripe.createCustomer({ email: 'user@example.com' });
+```

package/starter/.cursor/skills/hive-auth/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: hive-auth
+description: How authentication works in Hive framework
+globs:
+  - src/resources/auth/**/*.js
+alwaysApply: false
+---
+
+# Authentication
+
+Hive provides auth infrastructure but **no built-in auth endpoints**. You implement login/signup yourself.
+
+## Built-in (in .hive/)
+
+- `tokens` collection - stores access tokens
+- `attachUser` middleware - loads user from token
+- `isAuthorized` middleware - requires auth
+- `allowNoAuth` middleware - skips auth
+
+## How It Works
+
+1. Token extracted from cookie `access_token` or `Authorization: Bearer` header
+2. Token looked up in `tokens` collection
+3. User loaded from `users` collection
+4. User attached to `ctx.state.user`
+
+## Token Schema (built-in)
+
+```javascript
+{
+  _id: string,
+  user: { _id: string },
+  token: string,
+  metadata: object (optional),
+}
+```
+
+## Implement Auth Endpoints
+
+**1. Create token helper:**
+```javascript
+// src/resources/auth/methods/createToken.js
+import db from 'db';
+import crypto from 'crypto';
+
+const tokenService = db.services.tokens;
+
+export default async (ctx, { userId, metadata }) => {
+  const token = crypto.randomBytes(32).toString('hex');
+  
+  await tokenService.create({
+    token,
+    user: { _id: userId },
+    ...(metadata && { metadata }),
+  });
+  
+  ctx.cookies.set('access_token', token, {
+    httpOnly: false,
+    expires: new Date(Date.now() + 10 * 365 * 24 * 60 * 60 * 1000),
+  });
+  
+  return { token };
+};
+```
+
+**2. Login endpoint:**
+```javascript
+// src/resources/auth/endpoints/login.js
+import { z } from 'zod';
+import db from 'db';
+import bcrypt from 'bcrypt';
+import createToken from '../methods/createToken';
+
+export const handler = async (ctx) => {
+  const { email, password } = ctx.validatedData;
+  
+  const user = await db.services.users.findOne(
+    { email },
+    { isIncludeSecureFields: true }
+  );
+  ctx.assert(user, 401, 'Invalid credentials');
+  
+  const valid = await bcrypt.compare(password, user.password);
+  ctx.assert(valid, 401, 'Invalid credentials');
+  
+  const { token } = await createToken(ctx, { userId: user._id });
+  return { user, token };
+};
+
+export const middlewares = ['allowNoAuth'];
+export const endpoint = { url: '/login', method: 'post' };
+export const requestSchema = z.object({
+  email: z.string().email(),
+  password: z.string(),
+});
+```
+
+**3. Logout endpoint:**
+```javascript
+// src/resources/auth/endpoints/logout.js
+import { z } from 'zod';
+import db from 'db';
+
+export const handler = async (ctx) => {
+  await db.services.tokens.remove({ token: ctx.state.accessToken });
+  ctx.cookies.set('access_token', null);
+  return { success: true };
+};
+
+export const endpoint = { url: '/logout', method: 'post' };
+export const requestSchema = z.object({});
+```
+
+## Users Schema (add password)
+
+```javascript
+// src/resources/users/users.schema.js
+password: z.coerce.string().nullable().optional(),
+
+// Hide from responses
+export const secureFields = ['password'];
+```
+
+## Client Usage
+
+**Browser (cookies):**
+```javascript
+await fetch('/auth/login', { method: 'POST', credentials: 'include', body });
+```
+
+**API (header):**
+```javascript
+await fetch('/tasks', { headers: { Authorization: `Bearer ${token}` } });
+```