zyket 1.0.53 → 1.0.55

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "zyket",
+  "owner": {
+    "name": "PemaK"
+  },
+  "metadata": {
+    "description": "A collection of Claude plugins for building Zyket apps",
+    "version": "1.0.8"
+  },
+  "plugins": [
+    {
+      "name": "zyket",
+      "source": "./claude-plugin"
+    }
+  ]
+}

package/claude-plugin/.claude-plugin/commands/event.md

@@ -0,0 +1,29 @@
+# Create a Zyket Event
+
+Create a new event file in the Zyket project.
+
+## Instructions
+
+Events live in `src/events/`. The filename (without `.js`) is the event name used in `emit()`.
+
+### Template
+
+```js
+const { Event } = require("zyket");
+
+module.exports = class $EventName$Event extends Event {
+  async handle({ container, payload }) {
+    container.get("logger").info("$EventName$ event fired", payload);
+    // Your event logic here
+  }
+};
+```
+
+### Steps:
+1. Create `src/events/$event-name$.js`.
+2. Implement the handler logic based on the user's description.
+3. Show the user how to emit it:
+   ```js
+   container.get("events").emitAsync("$event-name$", { ...payload });
+   ```
+4. Remind the user to set `DISABLE_EVENTS=false` in `.env`.

package/claude-plugin/.claude-plugin/commands/guard.md

@@ -0,0 +1,37 @@
+# Create a Zyket Socket.IO Guard
+
+Create a new Socket.IO guard file in the Zyket project.
+
+## Instructions
+
+Guards live in `src/guards/`. The filename (without `.js`) is the guard name used in handler `guards` arrays. Guards run before an event handler or connection and can block execution by throwing an error.
+
+### Template
+
+```js
+const { Guard } = require("zyket");
+
+module.exports = class $Name$Guard extends Guard {
+  async handle({ container, socket, io }) {
+    // Validate / authorize the socket
+    // Throw an error to block the event or connection
+    // e.g.:
+    const token = socket.handshake.auth?.token;
+    if (!token) throw new Error("Unauthorized");
+
+    // Attach data to socket for handlers to use
+    // socket.data.user = verifiedUser;
+  }
+};
+```
+
+### Steps:
+1. Create `src/guards/$name$.js`.
+2. Implement the authorization logic.
+3. Show how to attach it to a handler:
+   ```js
+   module.exports = class MyHandler extends Handler {
+     guards = ["$name$"];
+     // ...
+   };
+   ```

package/claude-plugin/.claude-plugin/commands/handler.md

@@ -0,0 +1,37 @@
+# Create a Zyket Socket.IO Handler
+
+Create a new Socket.IO event handler file in the Zyket project.
+
+## Instructions
+
+Handlers live in `src/handlers/`. The filename (without `.js`) is the Socket.IO event name. The special file `connection.js` is the connection handler.
+
+### Event Handler Template
+
+```js
+const { Handler } = require("zyket");
+
+module.exports = class $EventName$Handler extends Handler {
+  guards = []; // optional: list guard filenames (without .js) to run first
+
+  async handle({ container, socket, data, io }) {
+    container.get("logger").info(`$EventName$ from ${socket.id}`, data);
+
+    // Your event handling logic here
+
+    // Return value is sent back via ack callback (if client uses acks)
+    return { success: true };
+  }
+};
+```
+
+### Steps:
+1. Create `src/handlers/$event-name$.js`.
+2. Add guard names to the `guards` array if authorization is needed.
+3. Implement the event handling logic.
+4. Optionally show the client-side code to emit the event:
+   ```js
+   socket.emit("$event-name$", { ...data }, (response) => {
+     console.log(response); // { success: true }
+   });
+   ```

package/claude-plugin/.claude-plugin/commands/middleware.md

@@ -0,0 +1,28 @@
+# Create a Zyket Middleware
+
+Create a new Express middleware file in the Zyket project.
+
+## Instructions
+
+Create a middleware class inside `src/middlewares/`. Middlewares must extend `Middleware` from `zyket` and implement the `handle` method.
+
+### Template
+
+```js
+const { Middleware } = require("zyket");
+
+module.exports = class $ClassName$Middleware extends Middleware {
+  async handle({ container, request, response, next }) {
+    // Your logic here
+    // Call next() to allow the request to continue
+    // Or return response.status(401).json({ success: false, message: "..." }) to block
+    next();
+  }
+};
+```
+
+### Steps:
+1. Create `src/middlewares/$name$.js` where `$name$` describes the purpose.
+2. Implement the validation/authentication/transformation logic.
+3. Call `next()` to pass the request through, or send a response to block.
+4. Show the user how to attach it to a route.

package/claude-plugin/.claude-plugin/commands/model.md

@@ -0,0 +1,40 @@
+# Create a Zyket Sequelize Model
+
+Create a new Sequelize model file in the Zyket project.
+
+## Instructions
+
+Models live in `src/models/`. Each file must export a **function** (not a class) that receives `{ sequelize, Sequelize, container }` and returns a Sequelize model instance.
+
+### Template
+
+```js
+const { DataTypes } = require("sequelize");
+
+module.exports = ({ sequelize, Sequelize, container }) => {
+  const $ModelName$ = sequelize.define("$ModelName$", {
+    id: {
+      type: DataTypes.INTEGER,
+      primaryKey: true,
+      autoIncrement: true,
+    },
+    // Add your fields here
+  }, {
+    tableName: "$table_name$",
+    timestamps: true,
+  });
+
+  $ModelName$.associate = (models) => {
+    // Define associations here
+    // $ModelName$.belongsTo(models.User, { foreignKey: "userId" });
+  };
+
+  return $ModelName$;
+};
+```
+
+### Steps:
+1. Create `src/models/$ModelName$.js`.
+2. Define all columns based on the user's description.
+3. Add associations if the model relates to other models.
+4. Optionally create a migration file in `src/models/migrations/`.

package/claude-plugin/.claude-plugin/commands/route.md

@@ -0,0 +1,42 @@
+# Create a Zyket Route
+
+Create a new HTTP route file in the Zyket project.
+
+## Instructions
+
+Given a route path or description from the user, create the appropriate file inside `src/routes/` following Zyket's file-based routing conventions.
+
+### File location rules:
+- `/users` → `src/routes/users.js`
+- `/users/:id` → `src/routes/users/[id].js`
+- `/users/:id/posts` → `src/routes/users/[id]/posts.js`
+- `/` (root) → `src/routes/index.js`
+
+### Template
+
+```js
+const { Route } = require("zyket");
+
+module.exports = class $ClassName$Route extends Route {
+  // Add middlewares if needed:
+  // middlewares = {
+  //   get: [new SomeMiddleware()],
+  //   post: [new SomeMiddleware()],
+  // };
+
+  async get({ container, request }) {
+    return {};
+  }
+
+  async post({ container, request }) {
+    return { status: 201 };
+  }
+};
+```
+
+### Steps:
+1. Determine the correct file path based on the route the user wants.
+2. Identify which HTTP methods are needed (get, post, put, delete).
+3. Implement each method based on the user's described functionality.
+4. Add middlewares if the route needs authentication or validation.
+5. Use `container.get("database")` to access models, `container.get("cache")` for caching, etc.

package/claude-plugin/.claude-plugin/commands/schedule.md

@@ -0,0 +1,38 @@
+# Create a Zyket Schedule
+
+Create a new cron-based scheduled task in the Zyket project.
+
+## Instructions
+
+Schedulers live in `src/schedulers/`. Each file exports a class extending `Schedule` from `zyket`. The `time` property must be a valid `node-cron` expression.
+
+### Template
+
+```js
+const { Schedule } = require("zyket");
+
+module.exports = class $Name$Schedule extends Schedule {
+  time = "$cron-expression$"; // e.g. "0 * * * *" for every hour
+
+  async handle({ container }) {
+    container.get("logger").info("Running $Name$ schedule");
+    // Your scheduled logic here
+  }
+};
+```
+
+### Common cron expressions
+
+| Pattern | Meaning |
+|---|---|
+| `* * * * *` | Every minute |
+| `0 * * * *` | Every hour |
+| `0 0 * * *` | Every day at midnight |
+| `0 9 * * 1` | Every Monday at 9:00 |
+| `*/5 * * * *` | Every 5 minutes |
+
+### Steps:
+1. Create `src/schedulers/$name$.js`.
+2. Set `time` to the appropriate cron expression.
+3. Implement the recurring task logic.
+4. Remind the user to set `DISABLE_SCHEDULER=false` in `.env`.

package/claude-plugin/.claude-plugin/commands/service.md

@@ -0,0 +1,59 @@
+# Create a Zyket Custom Service
+
+Create a new custom service in the Zyket project.
+
+## Instructions
+
+Custom services extend the `Service` base class and are registered in the `Kernel` constructor. They are booted once at startup and accessible anywhere via `container.get("serviceName")`.
+
+### Template
+
+```js
+// src/services/$name$.js
+const { Service } = require("zyket");
+
+module.exports = class $Name$Service extends Service {
+  #container;
+
+  constructor(container) {
+    super("$name$"); // Must match the registration name
+    this.#container = container;
+  }
+
+  async boot() {
+    // Initialize any connections, clients, etc.
+    this.#container.get("logger").info("$Name$Service booted");
+  }
+
+  // Add your service methods here
+};
+```
+
+### Registration
+
+```js
+// index.js
+const { Kernel } = require("zyket");
+const $Name$Service = require("./src/services/$name$");
+
+const kernel = new Kernel({
+  services: [
+    ["$name$", $Name$Service, ["@service_container"]],
+  ],
+});
+
+kernel.boot();
+```
+
+### Usage
+
+```js
+const service = container.get("$name$");
+```
+
+### Steps:
+1. Create `src/services/$name$.js`.
+2. Implement the `boot()` method for initialization.
+3. Add the service methods.
+4. Register it in `index.js` with a unique name.
+5. Use `"@service_container"` in the args array to inject the DI container.

package/claude-plugin/.claude-plugin/commands/worker.md

@@ -0,0 +1,39 @@
+# Create a Zyket BullMQ Worker
+
+Create a new BullMQ worker file in the Zyket project.
+
+## Instructions
+
+Workers live in `src/workers/`. Each file must export a class extending `Worker` from `zyket`.
+
+### Template
+
+```js
+const { Worker } = require("zyket");
+
+module.exports = class $WorkerName$Worker extends Worker {
+  queueName = "$queue-name$"; // Must match a name in the QUEUES env var
+
+  async handle({ container, job }) {
+    const data = job.data;
+    container.get("logger").info(`Processing job ${job.id}`, data);
+
+    // Your job logic here
+
+    return { success: true };
+  }
+};
+```
+
+### Steps:
+1. Create `src/workers/$worker-name$.js`.
+2. Set `queueName` to the appropriate queue name.
+3. Implement the job processing logic.
+4. Remind the user to:
+   - Add `DISABLE_BULLMQ=false` to `.env`
+   - Add the queue name to `QUEUES` in `.env` (e.g. `QUEUES=emails,notifications`)
+   - Set `CACHE_URL` in `.env`
+5. Show how to dispatch a job:
+   ```js
+   await container.get("queues").addJob("$queue-name$", "job-name", { ...data });
+   ```

package/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,133 @@
+{
+  "name": "zyket",
+  "description": "Comprehensive skills for building Zyket backends.",
+  "version": "1.0.8",
+  "author": {
+    "name": "PemaK"
+  },
+  "homepage": "https://zyket.com",
+  "repository": "https://github.com/PemaK/zyket-claude",
+  "keywords": [
+    "zyket",
+    "backend",
+    "admin",
+    "node.js",
+    "headless",
+    "api",
+    "database",
+    "authentication",
+    "authorization",
+    "file management",
+    "email",
+    "notifications",
+    "analytics",
+    "logging",
+    "testing",
+    "deployment",
+    "security"
+  ],
+  "skills": [
+    {
+      "name": "zyket-overview",
+      "description": "Overview of the Zyket framework, its architecture and project structure",
+      "file": "skills/overview.md"
+    },
+    {
+      "name": "zyket-routes",
+      "description": "How to create and configure Express HTTP routes in Zyket",
+      "file": "skills/routes.md"
+    },
+    {
+      "name": "zyket-middlewares",
+      "description": "How to create Express middlewares in Zyket",
+      "file": "skills/middlewares.md"
+    },
+    {
+      "name": "zyket-database",
+      "description": "How to define Sequelize models and run database migrations in Zyket",
+      "file": "skills/database.md"
+    },
+    {
+      "name": "zyket-events",
+      "description": "How to create and emit events in Zyket",
+      "file": "skills/events.md"
+    },
+    {
+      "name": "zyket-workers",
+      "description": "How to create BullMQ workers and manage job queues in Zyket",
+      "file": "skills/workers.md"
+    },
+    {
+      "name": "zyket-scheduler",
+      "description": "How to create cron-based scheduled tasks in Zyket",
+      "file": "skills/scheduler.md"
+    },
+    {
+      "name": "zyket-socketio",
+      "description": "How to create Socket.IO handlers and guards in Zyket",
+      "file": "skills/socketio.md"
+    },
+    {
+      "name": "zyket-auth",
+      "description": "How to set up authentication using better-auth in Zyket",
+      "file": "skills/auth.md"
+    },
+    {
+      "name": "zyket-services",
+      "description": "How to use built-in services (cache, S3, logger) and create custom services in Zyket",
+      "file": "skills/services.md"
+    },
+    {
+      "name": "zyket-extensions",
+      "description": "How to create and use extensions in Zyket",
+      "file": "skills/extensions.md"
+    }
+  ],
+  "commands": [
+    {
+      "name": "route",
+      "description": "Create a new HTTP route",
+      "file": "commands/route.md"
+    },
+    {
+      "name": "middleware",
+      "description": "Create a new Express middleware",
+      "file": "commands/middleware.md"
+    },
+    {
+      "name": "model",
+      "description": "Create a new Sequelize model",
+      "file": "commands/model.md"
+    },
+    {
+      "name": "event",
+      "description": "Create a new event",
+      "file": "commands/event.md"
+    },
+    {
+      "name": "worker",
+      "description": "Create a new BullMQ worker",
+      "file": "commands/worker.md"
+    },
+    {
+      "name": "schedule",
+      "description": "Create a new cron schedule",
+      "file": "commands/schedule.md"
+    },
+    {
+      "name": "handler",
+      "description": "Create a new Socket.IO event handler",
+      "file": "commands/handler.md"
+    },
+    {
+      "name": "guard",
+      "description": "Create a new Socket.IO guard",
+      "file": "commands/guard.md"
+    },
+    {
+      "name": "service",
+      "description": "Create a new custom service",
+      "file": "commands/service.md"
+    }
+  ]
+}

package/claude-plugin/.claude-plugin/skills/auth.md

@@ -0,0 +1,128 @@
+# Zyket – Authentication (better-auth)
+
+Zyket uses [better-auth](https://better-auth.com) for authentication. It only supports **PostgreSQL** as the database dialect.
+
+## Requirements
+
+```env
+DATABASE_URL=postgresql://user:password@localhost:5432/mydb
+DATABASE_DIALECT=postgresql
+CACHE_URL=redis://localhost:6379  # required for session secondary storage
+```
+
+## Creating an Auth Service
+
+Create a custom service that extends `AuthService`:
+
+```js
+// src/services/auth.js
+const { AuthService } = require("zyket");
+
+module.exports = class MyAuth extends AuthService {
+  // Add extra better-auth plugins
+  get plugins() {
+    return [];
+  }
+
+  // Add social providers (Google, GitHub, etc.)
+  get socialProviders() {
+    return {
+      google: {
+        clientId: process.env.GOOGLE_CLIENT_ID,
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      },
+    };
+  }
+
+  // Extra fields on the user table
+  get userAdditionalFields() {
+    return {
+      role: {
+        type: "string",
+        defaultValue: "user",
+        input: false, // cannot be set by user on sign-up
+      },
+    };
+  }
+
+  // Email hooks (implement or throw to disable)
+  async sendResetPasswordEmail({ user, url, token }, request) {
+    // Send email with the reset URL
+  }
+
+  async sendVerificationEmail({ user, url, token }, request) {
+    // Send email with the verification URL
+  }
+
+  async sendInvitationEmail(data) {
+    // Send org invitation email
+  }
+
+  async allowUserToCreateOrganization(user) {
+    return user.role === "admin"; // only admins can create orgs
+  }
+};
+```
+
+## Registering the Auth Service
+
+```js
+// index.js
+const { Kernel } = require("zyket");
+const MyAuth = require("./src/services/auth");
+
+const kernel = new Kernel({
+  services: [
+    ["auth", MyAuth, ["@service_container"]],
+  ],
+});
+
+kernel.boot();
+```
+
+## Endpoints Provided
+
+All better-auth REST endpoints are mounted at `/api/auth/*`. This includes:
+
+- `POST /api/auth/sign-up/email`
+- `POST /api/auth/sign-in/email`
+- `POST /api/auth/sign-out`
+- `POST /api/auth/forget-password`
+- `POST /api/auth/reset-password`
+- `GET  /api/auth/session`
+- `GET  /api/auth/verify-email`
+- Social provider OAuth flows (`/api/auth/sign-in/:provider`)
+- Admin routes (`/api/auth/admin/...`)
+- Organization routes (`/api/auth/organization/...`)
+
+## Verifying Sessions in Routes
+
+Use the `auth` property on the service or use `better-auth/node` token utilities:
+
+```js
+// src/middlewares/auth.js
+const { Middleware } = require("zyket");
+
+module.exports = class AuthMiddleware extends Middleware {
+  async handle({ container, request, response, next }) {
+    const auth = container.get("auth").client;
+    const session = await auth.api.getSession({ headers: request.headers });
+    if (!session) {
+      return response.status(401).json({ success: false, message: "Unauthorized" });
+    }
+    request.user = session.user;
+    next();
+  }
+};
+```
+
+## Built-in Plugins Included
+
+The base `AuthService` always includes:
+- `admin` – admin panel routes + `banUser`, `unbanUser`, `listUsers`, etc.
+- `bearer` – Bearer token support (for API use)
+- `organization` – multi-tenancy / organisations
+
+## Cookie Configuration
+
+Cookies are configured for cross-subdomain, `SameSite=none`, `Secure=true` by default (suitable for separate frontend/backend domains).