@archlast/server 0.1.0 → 0.1.1

package/README.md

@@ -407,12 +407,12 @@ export const processImage = action({
 Explicit HTTP endpoints with full control over request/response.
 
 ```ts
-import { http } from "@archlast/server/functions/definition";
+import { http } from "@archlast/server/http/definition";
 
 // GET route
 export const health = http.get({
   path: "/health",
-  handler: async () => {
+  handler: async (ctx) => {
     return new Response("ok", { status: 200 });
   },
 });
@@ -420,8 +420,8 @@ export const health = http.get({
 // POST route with body parsing
 export const createWebhook = http.post({
   path: "/api/webhooks",
-  handler: async (ctx, request) => {
-    const body = await request.json();
+  handler: async (ctx) => {
+    const body = await ctx.req.json();
     // Process webhook...
     return Response.json({ received: true });
   },
@@ -430,8 +430,9 @@ export const createWebhook = http.post({
 // Route with path parameters
 export const getUser = http.get({
   path: "/api/users/:id",
-  handler: async (ctx, request, params) => {
-    const user = await ctx.db.get("users", params.id);
+  handler: async (ctx) => {
+    const userId = ctx.req.params.id;
+    const user = await ctx.server.db.get("users", userId);
     if (!user) {
       return new Response("Not found", { status: 404 });
     }
@@ -440,41 +441,76 @@ export const getUser = http.get({
 });
 
 // Other methods
-http.put({ path: "/api/resource/:id", handler: async (ctx, req) => { /* ... */ } });
-http.patch({ path: "/api/resource/:id", handler: async (ctx, req) => { /* ... */ } });
-http.delete({ path: "/api/resource/:id", handler: async (ctx, req) => { /* ... */ } });
-http.options({ path: "/api/resource", handler: async () => { /* ... */ } });
+export const updateResource = http.put({
+  path: "/api/resource/:id",
+  handler: async (ctx) => {
+    const id = ctx.req.params.id;
+    const data = await ctx.req.json();
+    // Update resource...
+    return Response.json({ success: true });
+  },
+});
+
+export const patchResource = http.patch({
+  path: "/api/resource/:id",
+  handler: async (ctx) => { /* ... */ return Response.json({ success: true }); },
+});
+
+export const deleteResource = http.delete({
+  path: "/api/resource/:id",
+  handler: async (ctx) => { /* ... */ return new Response(null, { status: 204 }); },
+});
+
+export const optionsResource = http.options({
+  path: "/api/resource",
+  handler: async (ctx) => { return new Response(null, { status: 204 }); },
+});
 ```
 
 ### Webhooks
 
-Signed webhook handlers with automatic verification.
+Webhook handlers with custom security guards.
 
 ```ts
-import { webhook } from "@archlast/server/functions/definition";
+import { webhook } from "@archlast/server/webhook/definition";
+import { createSignatureGuard } from "@archlast/server/webhook/guard";
 
+// Stripe webhook with signature verification
 export const stripeWebhook = webhook({
   path: "/webhooks/stripe",
-  secret: process.env.STRIPE_WEBHOOK_SECRET!,
+  method: "POST",
+  guards: [
+    createSignatureGuard({
+      secret: process.env.STRIPE_WEBHOOK_SECRET!,
+      header: "stripe-signature",
+      algorithm: "sha256",
+    }),
+  ],
   handler: async (ctx, event) => {
     switch (event.type) {
       case "checkout.session.completed":
-        await handleCheckoutComplete(ctx, event.data);
+        await ctx.db.insert("orders", { userId: event.data.customer });
         break;
       case "customer.subscription.deleted":
-        await handleSubscriptionCanceled(ctx, event.data);
+        await ctx.db.update("users", event.data.customer, { subscribed: false });
         break;
     }
     return { received: true };
   },
 });
 
+// GitHub webhook with signature verification
 export const githubWebhook = webhook({
   path: "/webhooks/github",
-  secret: process.env.GITHUB_WEBHOOK_SECRET!,
-  signatureHeader: "X-Hub-Signature-256",
+  guards: [
+    createSignatureGuard({
+      secret: process.env.GITHUB_WEBHOOK_SECRET!,
+      header: "X-Hub-Signature-256",
+      algorithm: "sha256",
+    }),
+  ],
   handler: async (ctx, payload) => {
-    console.log("GitHub event:", payload.action);
+    ctx.logger.info("GitHub event received", { action: payload.action });
     return { ok: true };
   },
 });
@@ -486,22 +522,29 @@ Type-safe RPC procedures with automatic router generation.
 
 ```ts
 import { rpc } from "@archlast/server/functions/definition";
+import { z } from "zod";
 
 // RPC query
 export const getTasks = rpc.query({
-  args: { completed: v.boolean().optional().zodSchema },
+  args: z.object({
+    completed: z.boolean().optional(),
+  }),
   handler: async (ctx, args) => {
-    return ctx.db.query("tasks")
-      .where(args.completed !== undefined ? { completed: args.completed } : {})
-      .findMany();
+    const query = ctx.db.query("tasks");
+    if (args.completed !== undefined) {
+      query.where({ completed: args.completed });
+    }
+    return query.findMany();
   },
 });
 
 // RPC mutation
 export const createTask = rpc.mutation({
-  args: { text: v.string().zodSchema },
+  args: z.object({
+    text: z.string(),
+  }),
   handler: async (ctx, args) => {
-    return ctx.db.insert("tasks", { text: args.text });
+    return ctx.db.insert("tasks", { text: args.text, completed: false });
   },
 });
 ```
@@ -542,15 +585,49 @@ interface ActionCtx extends MutationCtx {
 
 ### AuthContext
 
+The auth context is populated from Better-Auth session data:
+
 ```ts
 interface AuthContext {
+  // User ID from Better-Auth session
   userId: string | null;
+
+  // Session ID from Better-Auth
   sessionId: string | null;
+
+  // Whether the request is authenticated
   isAuthenticated: boolean;
-  user: User | null;
+
+  // Better-Auth user object
+  user: {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name?: string;
+    image?: string;
+    role?: string;        // "user", "admin", "super-admin"
+    banned?: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+  } | null;
+
+  // Tenant/Organization info (if using organizations)
+  tenant?: {
+    id: string;
+    name: string;
+    ownerId: string;
+  } | null;
+
+  // Membership info
+  membership?: {
+    role: string;
+    permissions: string[];
+  } | null;
 }
 ```
 
+**Note:** Better-Auth stores users in `system_auth_user` collection with the `id` field (not `_id`). The adapter handles mapping automatically.
+
 ### Usage Examples
 
 ```ts
@@ -596,15 +673,49 @@ export const myAction = action(async (ctx) => {
 
 ## Authentication & Permissions
 
+Archlast uses [Better-Auth](https://www.better-auth.com/) for authentication. The server mounts Better-Auth at `/api/auth/*` and includes these plugins:
+
+- **Email/Password**: Standard credential authentication via `signIn.email()`
+- **Username**: Username-based sign-in via `signIn.username()`
+- **Anonymous**: Guest user support via `signIn.anonymous()`
+- **Admin**: User management, roles, bans, impersonation
+- **API Key**: Programmatic access with `arch_` prefixed keys
+- **Organization**: Multi-tenancy support
+
+### Sign-In Methods
+
+```ts
+// Email-based sign-in (web app pattern)
+await authClient.signIn.email({ email: "user@example.com", password: "..." });
+
+// Username-based sign-in (dashboard pattern)
+await authClient.signIn.username({ username: "admin", password: "..." });
+
+// Anonymous/guest sign-in
+await authClient.signIn.anonymous();
+```
+
+### Better-Auth Configuration
+
+Better-Auth is configured in the server with these features:
+
+```ts
+// Environment variables for Better-Auth
+BETTER_AUTH_SECRET=your-32-char-secret    // Required in production
+APP_URL=https://your-app.com               // Base URL for redirects
+ARCHLAST_ALLOWED_ORIGINS=http://localhost:3000  // Trusted origins (CSV)
+```
+
 ### Auth Modes
 
 All functions default to requiring authentication. Override with `auth` option:
 
 ```ts
-// Required (default) - must be authenticated
+// Required (default) - must be authenticated via Better-Auth
 export const privateQuery = query({
   handler: async (ctx) => {
     // ctx.auth.userId is guaranteed to exist
+    // ctx.auth.user contains Better-Auth user object
   },
 });
 
@@ -613,9 +724,9 @@ export const optionalAuth = query({
   auth: "optional",
   handler: async (ctx) => {
     if (ctx.auth.isAuthenticated) {
-      // Authenticated user
+      // Authenticated user via Better-Auth
     } else {
-      // Anonymous user
+      // Anonymous/guest user
     }
   },
 });
@@ -666,13 +777,20 @@ export const scheduleCleanup = mutation(async (ctx) => {
     payload: { olderThanDays: 30 },
   });
 
-  // Run in 5 minutes
+  // Run every 5 minutes
   await ctx.scheduler.schedule({
     name: "sendReminder",
-    preset: SchedulePreset.In5Minutes,
+    preset: SchedulePreset.Every5Minutes,
     payload: { userId: ctx.auth.userId },
   });
 
+  // Run every 10 minutes
+  await ctx.scheduler.schedule({
+    name: "syncData",
+    preset: SchedulePreset.Every10Minutes,
+    payload: {},
+  });
+
   // Recurring with cron
   await ctx.scheduler.schedule({
     name: "dailyReport",
@@ -684,23 +802,30 @@ export const scheduleCleanup = mutation(async (ctx) => {
 
 ### Schedule Presets
 
-| Preset | Description |
-|--------|-------------|
-| `RunNow` | Execute immediately |
-| `EveryMinute` | Run every minute |
-| `Every5Minutes` | Run every 5 minutes |
-| `Every15Minutes` | Run every 15 minutes |
-| `Every30Minutes` | Run every 30 minutes |
-| `Hourly` | Run every hour |
-| `Every6Hours` | Run every 6 hours |
-| `Every12Hours` | Run every 12 hours |
-| `DailyMidnight` | Daily at midnight UTC |
-| `DailyNoon` | Daily at noon UTC |
-| `Weekly` | Weekly on Sunday midnight |
-| `Monthly` | Monthly on the 1st |
-| `In5Minutes` | Once, 5 minutes from now |
-| `In1Hour` | Once, 1 hour from now |
-| `In1Day` | Once, 24 hours from now |
+| Preset | Cron Expression | Description |
+|--------|-----------------|-------------|
+| `RunNow` | (immediate) | Execute immediately |
+| `EveryMinute` | `* * * * *` | Run every minute |
+| `Every5Minutes` | `*/5 * * * *` | Run every 5 minutes |
+| `Every10Minutes` | `*/10 * * * *` | Run every 10 minutes |
+| `Every30Minutes` | `*/30 * * * *` | Run every 30 minutes |
+| `Hourly` | `0 * * * *` | Run every hour |
+| `Every8Hours` | `0 */8 * * *` | Run every 8 hours |
+| `Every16Hours` | `0 */16 * * *` | Run every 16 hours |
+| `DailyMidnight` | `0 0 * * *` | Daily at midnight UTC |
+| `Weekly` | `0 0 * * 0` | Weekly on Sunday midnight |
+| `Monthly` | `0 0 1 * *` | Monthly on the 1st |
+| `Quarterly` | `0 0 1 */3 *` | Quarterly (every 3 months) |
+
+You can also use custom cron expressions:
+
+```ts
+await ctx.scheduler.schedule({
+  name: "customJob",
+  cron: "0 9 * * 1-5", // Weekdays at 9 AM
+  payload: {},
+});
+```
 
 ---
 
@@ -740,14 +865,28 @@ Import only what you need:
 |--------|-------------|
 | `@archlast/server/schema/definition` | `defineSchema`, `defineTable`, relationship helpers |
 | `@archlast/server/schema/validators` | `v` validator object |
-| `@archlast/server/functions/definition` | `query`, `mutation`, `action`, `http`, `webhook`, `rpc` |
+| `@archlast/server/functions/definition` | `query`, `mutation`, `action`, `rpc` |
 | `@archlast/server/functions/types` | Context types, function types |
-| `@archlast/server/http` | HTTP handler utilities |
-| `@archlast/server/webhook` | Webhook handler utilities |
-| `@archlast/server/jobs` | `SchedulePreset`, job types |
+| `@archlast/server/http/definition` | `http` route builder |
+| `@archlast/server/http/router` | HTTP router utilities |
+| `@archlast/server/http` | HTTP utilities |
+| `@archlast/server/webhook/definition` | `webhook` function builder |
+| `@archlast/server/webhook/guard` | Webhook guard utilities |
+| `@archlast/server/webhook/verifier` | Signature verification |
+| `@archlast/server/webhook` | Webhook utilities |
+| `@archlast/server/jobs` | `SchedulePreset`, `Scheduler`, `JobQueue` |
+| `@archlast/server/jobs/scheduler` | Scheduler class and presets |
+| `@archlast/server/jobs/queue` | Job queue implementation |
 | `@archlast/server/storage/types` | Storage type definitions |
-| `@archlast/server/context` | Context type exports |
-| `@archlast/server/di/*` | Dependency injection utilities |
+| `@archlast/server/context` | Server context exports |
+| `@archlast/server/db/interfaces` | Database interface types |
+| `@archlast/server/auth/interfaces` | Auth interface types |
+| `@archlast/server/repository/interfaces` | Repository interface types |
+| `@archlast/server/repository/factory` | Repository factory |
+| `@archlast/server/di/decorators` | DI decorators |
+| `@archlast/server/di/container` | DI container |
+| `@archlast/server/logging/logger` | Logger service |
+| `@archlast/server/docker` | Docker utilities |
 
 ---
 
@@ -755,6 +894,16 @@ Import only what you need:
 
 Key variables used by the server runtime:
 
+### Better-Auth Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BETTER_AUTH_SECRET` | - | **Required in production.** Secret for signing tokens |
+| `APP_URL` | `http://localhost:4000` | Base URL for auth redirects |
+| `BETTER_AUTH_DEBUG` | `false` | Enable debug logging |
+
+### Server Configuration
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PORT` | `4000` | HTTP server port |
@@ -762,6 +911,11 @@ Key variables used by the server runtime:
 | `ARCHLAST_DB_ROOT` | `./data` | Database file directory |
 | `ARCHLAST_ALLOWED_ORIGINS` | - | CORS allowed origins (CSV) |
 | `ARCHLAST_CORS_ALLOW_CREDENTIALS` | `false` | Allow credentials in CORS |
+
+### Storage Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
 | `STORAGE_ROOT` | `./storage` | Local file storage directory |
 | `STORAGE_SIGNING_SECRET` | - | Secret for signed URLs |
 | `S3_ENABLED` | `false` | Enable S3 storage |
@@ -769,7 +923,11 @@ Key variables used by the server runtime:
 | `S3_REGION` | `us-east-1` | S3 region |
 | `AWS_ACCESS_KEY_ID` | - | AWS access key |
 | `AWS_SECRET_ACCESS_KEY` | - | AWS secret key |
-| `ARCHLAST_AUTH_TOKEN_PEPPER` | - | Token signing pepper |
+
+### Dashboard & Store Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
 | `ARCHLAST_DASHBOARD_DIR` | - | Dashboard static files path |
 | `ARCHLAST_DASHBOARD_URL` | - | Dashboard proxy URL |
 | `ARCHLAST_STORE_PORT` | `7001` | Document store port |
@@ -792,9 +950,9 @@ The CLI uses these templates when running `archlast start`.
 
 ---
 
-## Publishing (Maintainers)
+## Keywords
 
-See `docs/npm-publishing.md` for release and publish steps.
+archlast, server, backend, reactive, real-time, websocket, typescript, api, baas
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@archlast/server",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "description": "Archlast server library exports and Docker templates",
     "license": "MIT",
     "repository": {