@paralect/hive 0.1.49 → 0.1.50-alpha.0

package/test-app/.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/test-app/.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/test-app/.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}` } });
+```

package/test-app/.cursor/skills/hive-database/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: hive-database
+description: Database operations in Hive framework
+globs:
+  - src/**/*.js
+alwaysApply: false
+---
+
+# Database Operations
+
+## Access Service
+
+```javascript
+import db from 'db';
+const taskService = db.services.tasks;  // From schema name
+```
+
+## Find Operations
+
+```javascript
+// Find many
+const { results, pagesCount, count } = await service.find(
+  { status: 'active' },
+  { page: 1, perPage: 20, sort: '-createdOn', fields: ['_id', 'title'] }
+);
+
+// Find one
+const doc = await service.findOne({ _id: id });
+
+// Check exists
+const exists = await service.exists({ _id: id });
+
+// Count
+const total = await service.count({ status: 'active' });
+
+// Distinct values
+const statuses = await service.distinct('status');
+
+// Aggregate
+const { results } = await service.aggregate([
+  { $match: { status: 'done' } },
+  { $group: { _id: '$project._id', count: { $sum: 1 } } },
+]);
+```
+
+## Write Operations
+
+```javascript
+// Create
+const doc = await service.create({ title: 'New', user: ctx.state.user });
+
+// Update one (must use function)
+const updated = await service.updateOne(
+  { _id: id },
+  (doc) => ({ ...doc, title: 'Updated' })
+);
+
+// Update many
+await service.updateMany(
+  { status: 'pending' },
+  (doc) => ({ ...doc, status: 'active' })
+);
+
+// Remove
+await service.remove({ _id: id });
+
+// Generate ID
+const newId = service.generateId();
+```
+
+## Atomic Operations (No Events)
+
+```javascript
+// Silent bulk update
+await service.atomic.update(
+  { 'project._id': projectId },
+  { $set: { 'project.name': newName } },
+  { multi: true }
+);
+```
+
+## Query Patterns
+
+```javascript
+import { when } from 'services/utils';
+
+const { results } = await service.find({
+  // Conditional fields
+  ...when(status, { status }),
+  ...when(userId, { 'user._id': userId }),
+  
+  // Complex conditions
+  status: { $in: ['active', 'pending'] },
+  createdOn: { $gte: startDate, $lt: endDate },
+  $or: [{ 'user._id': id }, { isPublic: true }],
+});
+```
+
+## Rules
+
+- `updateOne` requires a function, not an object
+- Use `atomic.update` for bulk/silent updates
+- Use `when()` helper for conditional query building

package/test-app/.cursor/skills/hive-endpoint/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: hive-endpoint
+description: How to create API endpoints in Hive framework
+globs:
+  - src/resources/**/endpoints/*.js
+alwaysApply: false
+---
+
+# Creating Endpoints
+
+Location: `/src/resources/{name}/endpoints/{action}.js`
+
+## Template (4 Required Exports)
+
+```javascript
+import { z } from 'zod';
+import db from 'db';
+
+const myService = db.services.myResource;
+
+export const handler = async (ctx) => {
+  const { param } = ctx.validatedData;
+  // Logic here
+  return { result: 'data' };
+};
+
+export const middlewares = [];
+
+export const endpoint = {
+  url: '/',
+  method: 'get',
+};
+
+export const requestSchema = z.object({
+  param: z.coerce.string().nullable().optional(),
+});
+```
+
+## Handler Context (ctx)
+
+```javascript
+ctx.validatedData       // Validated input (body + query + params)
+ctx.state.user          // Authenticated user
+ctx.params              // URL params
+ctx.throw(404, 'msg')   // Throw error
+ctx.assert(cond, 400)   // Assert or throw
+```
+
+## Common Patterns
+
+**List:**
+```javascript
+export const handler = async (ctx) => {
+  const { page, perPage } = ctx.validatedData;
+  const { results, count } = await service.find(
+    { 'user._id': ctx.state.user._id },
+    { page, perPage, sort: '-createdOn' }
+  );
+  return { results, count };
+};
+export const endpoint = { url: '/', method: 'get' };
+```
+
+**Create:**
+```javascript
+export const handler = async (ctx) => {
+  const doc = await service.create({
+    ...ctx.validatedData,
+    user: ctx.state.user,
+  });
+  return doc;
+};
+export const endpoint = { url: '/', method: 'post' };
+```
+
+**Update:**
+```javascript
+export const handler = async (ctx) => {
+  const { id, title } = ctx.validatedData;
+  return await service.updateOne({ _id: id }, (doc) => ({ ...doc, title }));
+};
+export const endpoint = { url: '/:id', method: 'put' };
+```
+
+## Middlewares
+
+```javascript
+// By name
+export const middlewares = ['allowNoAuth'];
+
+// With args
+export const middlewares = [{ name: 'shouldExist', args: ['projects'] }];
+
+// Direct function
+import canEditProject from 'middlewares/canEditProject';
+export const middlewares = [canEditProject((ctx) => ctx.params.projectId)];
+```
+
+## Public Endpoint (No Auth)
+
+```javascript
+export const middlewares = ['allowNoAuth'];
+```