@paralect/hive 0.1.47 → 0.1.49

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}` } });
+```

package/starter/.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/starter/.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'];
+```

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

@@ -0,0 +1,88 @@
+---
+name: hive-handler
+description: How to create event handlers in Hive framework
+globs:
+  - src/resources/**/handlers/*.js
+alwaysApply: false
+---
+
+# Creating Event Handlers
+
+Handlers react to database events automatically.
+
+Location: `/src/resources/{name}/handlers/{handlerName}.js`
+
+## Template
+
+```javascript
+import db from 'db';
+
+const myService = db.services.myResource;
+
+myService.on('created', async ({ doc }) => {
+  // Handle creation
+});
+
+myService.on('updated', async ({ doc, prevDoc }) => {
+  // Handle update
+});
+
+myService.on('removed', async ({ doc }) => {
+  // Handle removal
+});
+```
+
+## Events
+
+| Event | Payload | Trigger |
+|-------|---------|---------|
+| `created` | `{ doc }` | After `service.create()` |
+| `updated` | `{ doc, prevDoc }` | After `service.updateOne/Many()` |
+| `removed` | `{ doc }` | After `service.remove()` |
+
+## Common Patterns
+
+**Create related record:**
+```javascript
+taskService.on('created', async ({ doc }) => {
+  await eventService.create({
+    type: 'task.created',
+    data: { task: doc },
+    project: doc.project,
+  });
+});
+```
+
+**Update parent on child change:**
+```javascript
+docService.on('created', async ({ doc }) => {
+  if (doc.role === 'case-study') {
+    await projectService.updateOne(
+      { _id: doc.project._id },
+      (p) => ({ ...p, caseStudy: doc })
+    );
+  }
+});
+```
+
+**React to specific field change:**
+```javascript
+import ifUpdated from 'helpers/db/ifUpdated';
+
+taskService.on('updated', ifUpdated(['status'], async ({ doc, prevDoc }) => {
+  // Only runs when status changed
+}));
+```
+
+**Cleanup on delete:**
+```javascript
+docService.on('removed', async ({ doc }) => {
+  await eventService.remove({ 'data.doc._id': doc._id });
+});
+```
+
+## Rules
+
+- Keep handlers fast (don't block response)
+- Use `atomic.update` for silent bulk updates (no events)
+- Use `ifUpdated` helper to filter field changes

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

@@ -0,0 +1,85 @@
+---
+name: hive-mapping
+description: Schema mappings for auto-syncing embedded documents
+globs:
+  - src/autoMap/schemaMappings.json
+alwaysApply: false
+---
+
+# Schema Mappings
+
+Auto-sync embedded references when source documents change.
+
+Location: `/src/autoMap/schemaMappings.json`
+
+## How It Works
+
+1. You embed document references in schemas (e.g., `user: { _id, fullName }`)
+2. You register the mapping in `schemaMappings.json`
+3. When source document updates, all referencing documents sync automatically
+
+## Config Format
+
+```json
+{
+  "tasks": {
+    "user": {
+      "schema": "users"
+    },
+    "project": {
+      "schema": "projects"
+    }
+  }
+}
+```
+
+Means: In `tasks` collection, fields `user` and `project` reference `users` and `projects` collections.
+
+## Example
+
+**Schema with embedded reference:**
+```javascript
+// tasks.schema.js
+project: z
+  .object({
+    _id: z.string(),
+    name: z.coerce.string().nullable().optional(),
+    logoUrl: z.coerce.string().nullable().optional(),
+  })
+  .nullable()
+  .optional(),
+```
+
+**Mapping config:**
+```json
+{
+  "tasks": {
+    "project": {
+      "schema": "projects"
+    }
+  }
+}
+```
+
+**Result:** When project's `name` or `logoUrl` changes, all tasks with that project update automatically.
+
+## Adding New Mapping
+
+1. Define embedded reference in schema (include fields to sync)
+2. Add entry to `schemaMappings.json`:
+
+```json
+{
+  "yourResource": {
+    "fieldName": {
+      "schema": "sourceSchema"
+    }
+  }
+}
+```
+
+## Rules
+
+- Only fields defined in the embedded object shape are synced
+- Works for both single references and arrays
+- Changes sync on source document `updated` event