@shaferllc/keel 0.81.0 → 0.81.1

package/dist/teams/migration.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The teams schema: teams, memberships, invitations, and one column on users.
+ *
+ * `team_memberships` is what actually grants access — `teams.owner_id` is a
+ * convenience, not an authorization source. A user is in a team if and only if a
+ * membership row says so.
+ */
+import type { Migration } from "../core/migrations.js";
+export declare function teamsMigration(userTable?: string): Migration;

package/dist/teams/migration.js

@@ -0,0 +1,52 @@
+/**
+ * The teams schema: teams, memberships, invitations, and one column on users.
+ *
+ * `team_memberships` is what actually grants access — `teams.owner_id` is a
+ * convenience, not an authorization source. A user is in a team if and only if a
+ * membership row says so.
+ */
+export function teamsMigration(userTable = "users") {
+    return {
+        name: "teams_00_create_teams",
+        async up(schema) {
+            await schema.createTable("teams", (t) => {
+                t.id();
+                t.string("name");
+                t.string("slug").unique();
+                t.integer("owner_id");
+                t.timestamps();
+            });
+            await schema.createTable("team_memberships", (t) => {
+                t.id();
+                t.integer("team_id");
+                t.integer("user_id");
+                // owner | admin | member
+                t.string("role", 32).default("member");
+                t.timestamps();
+            });
+            await schema.createTable("team_invitations", (t) => {
+                t.id();
+                t.integer("team_id");
+                t.string("email");
+                t.string("role", 32).default("member");
+                // The token's HASH. The token itself lives in the invitee's inbox and
+                // nowhere else, so a database leak doesn't open every pending team.
+                t.string("token");
+                t.timestamp("expires_at");
+                t.timestamps();
+            });
+            // One membership per user per team, enforced by the database rather than by
+            // remembering to check — accepting an invitation twice must not double up.
+            await schema.raw("CREATE UNIQUE INDEX IF NOT EXISTS team_memberships_unique ON team_memberships (team_id, user_id)");
+            await schema.raw("CREATE INDEX IF NOT EXISTS team_invitations_email ON team_invitations (email)");
+            // Which team the user is currently looking at.
+            await schema.raw(`ALTER TABLE ${userTable} ADD COLUMN current_team_id INTEGER`);
+        },
+        async down(schema) {
+            await schema.dropTable("team_invitations");
+            await schema.dropTable("team_memberships");
+            await schema.dropTable("teams");
+            await schema.raw(`ALTER TABLE ${userTable} DROP COLUMN current_team_id`).catch(() => { });
+        },
+    };
+}

package/dist/teams/models.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Teams and membership.
+ *
+ * These are plain models, deliberately **not** `TenantModel` — the tenant scope
+ * constrains queries to the current team, and you have to be able to ask "which
+ * teams does this user belong to?" *before* you know which team you're in.
+ */
+import { Model } from "../core/model.js";
+/** Who can do what. Ordered: an owner can do anything an admin can, and so on. */
+export declare const ROLES: readonly ["owner", "admin", "member"];
+export type Role = (typeof ROLES)[number];
+/** Does `role` carry at least the authority of `needed`? */
+export declare function roleAtLeast(role: Role, needed: Role): boolean;
+export declare class Team extends Model {
+    static table: string;
+    static fillable: string[];
+    static timestamps: boolean;
+    id: number;
+    name: string;
+    slug: string;
+    owner_id: number;
+    /** Everyone in this team, with their role. */
+    members(): Promise<Membership[]>;
+}
+export declare class Membership extends Model {
+    static table: string;
+    static fillable: string[];
+    static timestamps: boolean;
+    id: number;
+    team_id: number;
+    user_id: number;
+    role: Role;
+}
+/** The teams a user belongs to. */
+export declare function teamsFor(userId: string | number): Promise<Team[]>;
+/** A user's role in a team, or `null` if they aren't in it. */
+export declare function roleOf(userId: string | number, teamId: string | number): Promise<Role | null>;
+/** Is this user in this team, at least at this level? */
+export declare function memberOf(userId: string | number, teamId: string | number, atLeast?: Role): Promise<boolean>;
+/**
+ * Create a team and make its creator the owner.
+ *
+ * The membership row is what actually grants access — `teams.owner_id` alone would
+ * leave the owner out of every membership query.
+ */
+export declare function createTeam(name: string, ownerId: string | number, slug?: string): Promise<Team>;
+/**
+ * Switch which team a user is acting as — **only** to a team they're actually in.
+ *
+ * The check is the point. `current_team_id` is a number on the user's own row; if
+ * switching didn't verify membership, changing teams would just be a matter of
+ * writing someone else's id into it.
+ */
+export declare function switchTeam(userId: string | number, teamId: string | number, userTable?: string): Promise<boolean>;

package/dist/teams/models.js

@@ -0,0 +1,85 @@
+/**
+ * Teams and membership.
+ *
+ * These are plain models, deliberately **not** `TenantModel` — the tenant scope
+ * constrains queries to the current team, and you have to be able to ask "which
+ * teams does this user belong to?" *before* you know which team you're in.
+ */
+import { Model } from "../core/model.js";
+import { db } from "../core/database.js";
+/** Who can do what. Ordered: an owner can do anything an admin can, and so on. */
+export const ROLES = ["owner", "admin", "member"];
+const RANK = { owner: 3, admin: 2, member: 1 };
+/** Does `role` carry at least the authority of `needed`? */
+export function roleAtLeast(role, needed) {
+    return RANK[role] >= RANK[needed];
+}
+export class Team extends Model {
+    static table = "teams";
+    static fillable = ["name", "slug", "owner_id"];
+    static timestamps = true;
+    /** Everyone in this team, with their role. */
+    async members() {
+        const rows = await db(Membership.table).where("team_id", this.id).get();
+        return rows.map((row) => new Membership(row));
+    }
+}
+export class Membership extends Model {
+    static table = "team_memberships";
+    static fillable = ["team_id", "user_id", "role"];
+    static timestamps = true;
+}
+/* --------------------------------- lookups -------------------------------- */
+/** The teams a user belongs to. */
+export async function teamsFor(userId) {
+    const memberships = await db(Membership.table).where("user_id", userId).get();
+    if (!memberships.length)
+        return [];
+    const ids = memberships.map((m) => m.team_id);
+    const rows = await db(Team.table).whereIn("id", ids).get();
+    return rows.map((row) => new Team(row));
+}
+/** A user's role in a team, or `null` if they aren't in it. */
+export async function roleOf(userId, teamId) {
+    const row = await db(Membership.table).where("user_id", userId).where("team_id", teamId).first();
+    return row ? row.role : null;
+}
+/** Is this user in this team, at least at this level? */
+export async function memberOf(userId, teamId, atLeast = "member") {
+    const role = await roleOf(userId, teamId);
+    return role ? roleAtLeast(role, atLeast) : false;
+}
+/**
+ * Create a team and make its creator the owner.
+ *
+ * The membership row is what actually grants access — `teams.owner_id` alone would
+ * leave the owner out of every membership query.
+ */
+export async function createTeam(name, ownerId, slug) {
+    const team = await Team.create({
+        name,
+        slug: slug ?? slugify(name),
+        owner_id: ownerId,
+    });
+    await Membership.create({ team_id: team.id, user_id: ownerId, role: "owner" });
+    return team;
+}
+/**
+ * Switch which team a user is acting as — **only** to a team they're actually in.
+ *
+ * The check is the point. `current_team_id` is a number on the user's own row; if
+ * switching didn't verify membership, changing teams would just be a matter of
+ * writing someone else's id into it.
+ */
+export async function switchTeam(userId, teamId, userTable = "users") {
+    if (!(await memberOf(userId, teamId)))
+        return false;
+    await db(userTable).where("id", userId).update({ current_team_id: teamId });
+    return true;
+}
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}

package/dist/teams/provider.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Teams — multi-tenancy, membership, roles, and invitations, shipped as a Keel
+ * package. One line in `bootstrap/providers.ts`:
+ *
+ *   app.register(TeamsServiceProvider)
+ *
+ * Then put your requests inside a team, and every `TenantModel` is scoped:
+ *
+ *   // app/Http/Kernel.ts
+ *   protected middleware = [sessionMiddleware(), teamContext()];
+ */
+import { PackageProvider } from "../core/package.js";
+export declare class TeamsServiceProvider extends PackageProvider {
+    readonly name = "teams";
+    private config;
+    register(): void;
+}

package/dist/teams/provider.js

@@ -0,0 +1,27 @@
+/**
+ * Teams — multi-tenancy, membership, roles, and invitations, shipped as a Keel
+ * package. One line in `bootstrap/providers.ts`:
+ *
+ *   app.register(TeamsServiceProvider)
+ *
+ * Then put your requests inside a team, and every `TenantModel` is scoped:
+ *
+ *   // app/Http/Kernel.ts
+ *   protected middleware = [sessionMiddleware(), teamContext()];
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { PackageProvider } from "../core/package.js";
+import { defaultConfig, resolveConfig } from "./config.js";
+import { teamsMigration } from "./migration.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export class TeamsServiceProvider extends PackageProvider {
+    name = "teams";
+    config;
+    register() {
+        this.mergeConfig("teams", defaultConfig);
+        this.config = resolveConfig();
+        this.migrations([teamsMigration(this.config.userTable)]);
+        this.publishes({ [join(here, "teams.config.stub")]: "config/teams.ts" }, "teams-config");
+    }
+}

package/dist/teams/teams.config.stub

@@ -0,0 +1,24 @@
+import { env } from "@shaferllc/keel/core";
+
+/**
+ * Teams configuration — multi-tenancy, membership, roles, invitations.
+ * Published with `keel vendor:publish --tag teams-config`.
+ */
+export default {
+  // The users table. Teams adds `current_team_id` to it and touches nothing else.
+  userTable: "users",
+
+  // Give every new user a team of their own. Worth leaving on even if the app feels
+  // single-user: a personal workspace is a team of one, and adding tenancy LATER
+  // means backfilling every table and rewriting every query.
+  personalTeams: true,
+
+  invitations: {
+    expiresInHours: 72,
+    url: "/invitations/:token",
+  },
+
+  mail: {
+    from: env("MAIL_FROM", undefined),
+  },
+};

package/dist/teams/tenant.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `TenantModel` — a model that belongs to a team, and can't be read or written
+ * outside one.
+ *
+ *   class Post extends TenantModel {
+ *     static table = "posts";
+ *   }
+ *
+ *   await Post.all();                 // only the current team's posts
+ *   await Post.create({ title: … });  // stamped with the current team
+ *
+ * Two halves, and both matter. The **read** side is a global scope, so every query
+ * the model builds is constrained — you cannot forget it, because you never write
+ * it. The **write** side is a `creating` hook that stamps the team id, so a row
+ * can't be born ownerless and then be visible to everyone (or to no one).
+ *
+ * Outside a team context both halves throw. See context.ts for why that's the point.
+ */
+import { Model } from "../core/model.js";
+/** The name of the scope, so it can be escaped by name: `Post.withoutGlobalScope(TENANT_SCOPE)`. */
+export declare const TENANT_SCOPE = "tenant";
+export declare class TenantModel extends Model {
+    /** The column holding the owning team. Override if your schema differs. */
+    static teamColumn: string;
+}

package/dist/teams/tenant.js

@@ -0,0 +1,45 @@
+/**
+ * `TenantModel` — a model that belongs to a team, and can't be read or written
+ * outside one.
+ *
+ *   class Post extends TenantModel {
+ *     static table = "posts";
+ *   }
+ *
+ *   await Post.all();                 // only the current team's posts
+ *   await Post.create({ title: … });  // stamped with the current team
+ *
+ * Two halves, and both matter. The **read** side is a global scope, so every query
+ * the model builds is constrained — you cannot forget it, because you never write
+ * it. The **write** side is a `creating` hook that stamps the team id, so a row
+ * can't be born ownerless and then be visible to everyone (or to no one).
+ *
+ * Outside a team context both halves throw. See context.ts for why that's the point.
+ */
+import { Model } from "../core/model.js";
+import { addModelHook } from "../core/model-events.js";
+import { currentTeamId } from "./context.js";
+/** The name of the scope, so it can be escaped by name: `Post.withoutGlobalScope(TENANT_SCOPE)`. */
+export const TENANT_SCOPE = "tenant";
+export class TenantModel extends Model {
+    /** The column holding the owning team. Override if your schema differs. */
+    static teamColumn = "team_id";
+}
+// Registered on the base class, and inherited by every subclass — that inheritance
+// is load-bearing. If it didn't hold, `Post.query()` would come back unconstrained
+// and every tenant's rows would be readable, silently. (Both the scope and the hook
+// walk the prototype chain; see model.ts / model-events.ts.)
+TenantModel.addGlobalScope(TENANT_SCOPE, (query, model) => {
+    // `model` is the concrete subclass being queried, so each one gets its own
+    // teamColumn rather than the base class's.
+    query.where(model.teamColumn, currentTeamId());
+});
+addModelHook(TenantModel, "creating", (model) => {
+    const column = model.constructor.teamColumn;
+    const row = model;
+    // Don't overwrite an explicit team — a deliberate cross-team write (an admin tool,
+    // a transfer) already said what it meant. Everything else gets the current team.
+    if (row[column] === undefined || row[column] === null) {
+        row[column] = currentTeamId();
+    }
+});

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.81.0",
+  "version": "0.81.1",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "repo": "https://github.com/shaferllc/keel",
   "generated": "run `npm run build:ai` to regenerate",
@@ -362,6 +362,13 @@
       "path": "docs/storage.md",
       "example": "docs/examples/storage.ts"
     },
+    {
+      "slug": "teams",
+      "title": "Teams",
+      "summary": "Multi-tenancy, membership, roles, and invitations — where a row belongs to a team, and one team can never see another's.",
+      "path": "docs/teams.md",
+      "example": "docs/examples/teams.ts"
+    },
     {
       "slug": "telemetry",
       "title": "Telemetry",

package/docs/database.md

@@ -609,6 +609,53 @@ await db("sessions").where("expires_at", "<", now).delete();
 **Notes:** with no `where`, empties the table. There's no soft-delete here — pair
 with a `deleted_at` column and `whereNull` if you want one.
 
+#### `whereColumn(first, operator?, second)` · `whereRaw(sql, bindings?)`
+
+Compare two columns (no binding) or add a raw WHERE fragment with its own
+bindings. `whereColumn("updated_at", ">", "created_at")`; `whereRaw("score >= ?", [10])`.
+
+#### `join(table, first, operator?, second)` · `leftJoin(...)`
+
+Add an `INNER JOIN` / `LEFT JOIN` on an equality (or the given operator).
+Included in `get`, `count`, and aggregates. Qualify ambiguous columns
+(`"posts.user_id"`).
+
+#### `groupBy(...columns)` · `having(column, operator?, value)` · `distinct()`
+
+`GROUP BY`, a bound `HAVING` predicate, and `SELECT DISTINCT`.
+
+#### `orderByRaw(sql)` · `when(condition, then, otherwise?)`
+
+A raw `ORDER BY` fragment; and conditional building — `then(query, value)` runs
+only when `condition` is truthy, else `otherwise`.
+
+#### `increment(column, amount?, extra?)` · `decrement(column, amount?, extra?)`
+
+`increment(column: string, amount = 1, extra: Row = {}): Promise<WriteResult>`
+
+Atomically `column = column ± amount` on matching rows, optionally setting other
+columns in the same statement. Scope with `where`.
+
+#### `upsert(rows, uniqueBy, update?)`
+
+`upsert(rows: Row | Row[], uniqueBy: string[], update?: string[]): Promise<WriteResult>`
+
+Insert rows, updating `update` columns (default: all non-unique) on a conflict
+against `uniqueBy`. Dialect-aware: `ON CONFLICT … DO UPDATE` (sqlite/postgres) or
+`ON DUPLICATE KEY UPDATE` (mysql).
+
+#### `insertOrIgnore(rows)`
+
+Insert one or more rows, skipping any that violate a unique constraint
+(`INSERT OR IGNORE` / `INSERT IGNORE` / `ON CONFLICT DO NOTHING`).
+
+#### `chunk(size, callback)`
+
+`chunk(size: number, callback: (rows: T[]) => void | boolean | Promise<void | boolean>): Promise<void>`
+
+Process results a page at a time so a large table never loads at once. Return
+`false` from the callback to stop early. Pair with `orderBy` for a stable order.
+
 ### Interfaces & types
 
 #### `Connection`

package/docs/examples/teams.ts

@@ -0,0 +1,101 @@
+// Typechecked example for docs/teams.md.
+import { Application, sessionMiddleware } from "@shaferllc/keel/core";
+import {
+  TeamsServiceProvider,
+  TenantModel,
+  TENANT_SCOPE,
+  acceptInvitation,
+  createTeam,
+  currentTeam,
+  invite,
+  memberOf,
+  pendingInvitations,
+  requireRole,
+  revokeInvitation,
+  roleAtLeast,
+  roleOf,
+  runForTeam,
+  switchTeam,
+  teamContext,
+  teamsFor,
+  withoutTenant,
+} from "@shaferllc/keel/teams";
+
+const app = new Application();
+app.register(TeamsServiceProvider);
+
+// Put every request inside a team; TenantModel queries are scoped from then on.
+const middleware = [sessionMiddleware(), teamContext()];
+
+/* -------------------------------- a tenant model -------------------------- */
+
+class Post extends TenantModel {
+  static override table = "posts";
+  static override fillable = ["title"];
+
+  declare id: number;
+  declare title: string;
+}
+
+async function inAHandler() {
+  const mine = await Post.all(); // only the current team's
+  const one = await Post.find(1); // null if it belongs to another team
+  const made = await Post.create({ title: "Hi" }); // stamped with the current team
+  return { mine, one, made, team: currentTeam() };
+}
+
+/* ------------------------------ outside a request ------------------------- */
+
+async function aJob(team: { id: number }) {
+  // Without this, the query throws — it does not quietly return every team's rows.
+  await runForTeam(team, async () => {
+    await Post.all();
+  });
+}
+
+async function anAdminReport() {
+  // Crossing tenants, said out loud so it can be found at audit time.
+  return withoutTenant(() => Post.withoutGlobalScope(TENANT_SCOPE).get());
+}
+
+/* --------------------------------- membership ----------------------------- */
+
+async function onboarding(userId: number) {
+  const team = await createTeam("Acme", userId);
+
+  await teamsFor(userId);
+  await roleOf(userId, team.id);
+  await memberOf(userId, team.id, "admin");
+  await switchTeam(userId, team.id); // false if they aren't a member
+
+  return team;
+}
+
+const adminsOnly = requireRole("admin");
+const ordered = roleAtLeast("owner", "admin"); // true
+
+/* -------------------------------- invitations ----------------------------- */
+
+async function inviteSomeone(teamId: number, userId: number) {
+  const { token, invitation } = await invite(teamId, "grace@example.com", "admin");
+
+  await pendingInvitations(teamId);
+  await revokeInvitation(invitation.id);
+
+  // The invited address is re-checked, so a forwarded link can't be redeemed by
+  // someone else.
+  return acceptInvitation(token, userId, "grace@example.com");
+}
+
+export {
+  app,
+  middleware,
+  Post,
+  inAHandler,
+  aJob,
+  anAdminReport,
+  onboarding,
+  adminsOnly,
+  ordered,
+  inviteSomeone,
+};

package/docs/migrations.md

@@ -285,11 +285,10 @@ already gone — the typical `down()` for a `createTable`.
 
 `raw(sql: string, bindings?: unknown[]): Promise<void>`
 
-Runs arbitrary SQL through the connection — the escape hatch for indexes, foreign
-keys, and `ALTER TABLE`.
+Runs arbitrary SQL through the connection — the escape hatch for anything the
+builders don't cover.
 
 ```ts
-await schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)");
 await schema.raw("UPDATE users SET active = ? WHERE active IS NULL", [true]);
 ```
 
@@ -297,6 +296,22 @@ await schema.raw("UPDATE users SET active = ? WHERE active IS NULL", [true]);
 `raw()` does **not** rewrite `?` to `$n`, so pass `$1, $2, …` yourself on the
 `postgres` dialect.
 
+#### `alterTable(name, build)`
+
+`alterTable(name: string, build: (table: AlterTableBuilder) => void): Promise<void>`
+
+Alter an existing table — the callback gets an [`AlterTableBuilder`](#altertablebuilder)
+for adding, renaming, and dropping columns and indexes. Emits one dialect-aware
+statement per operation, ordered so a dropped index precedes its column.
+
+```ts
+await schema.alterTable("users", (t) => {
+  t.string("phone").nullable();
+  t.renameColumn("name", "full_name");
+  t.dropColumn("legacy");
+});
+```
+
 ### `TableBuilder`
 
 Describes a table's columns. **You get one from the `createTable` callback** — it
@@ -413,6 +428,27 @@ t.toCreateSql("users", "postgres");
 // CREATE TABLE users (id SERIAL PRIMARY KEY, email VARCHAR(255) NOT NULL)
 ```
 
+#### `index(columns, name?)` / `uniqueIndex(columns, name?)`
+
+Add a (possibly composite) index or unique index; `columns` is a name or array.
+Emitted as `CREATE [UNIQUE] INDEX` after the table. Auto-named unless `name` is
+given.
+
+```ts
+t.index("email");
+t.uniqueIndex(["team_id", "slug"]);
+```
+
+#### `foreign(column)`
+
+`foreign(column: string): ForeignKeyBuilder`
+
+Add a foreign key, built fluently and emitted inline in the `CREATE TABLE`.
+
+```ts
+t.foreign("team_id").references("id").on("teams").onDelete("cascade");
+```
+
 #### `columns`
 
 `readonly columns: Column[]`
@@ -420,6 +456,21 @@ t.toCreateSql("users", "postgres");
 The `Column` instances added so far, in declaration order. Read-only inspection
 seam; you rarely touch it.
 
+### `AlterTableBuilder`
+
+From the `alterTable` callback. Column methods (`string`, `integer`, …) **add**
+columns; plus:
+
+- `dropColumn(name)` — drop a column.
+- `renameColumn(from, to)` — rename a column.
+- `index(columns, name?)` / `uniqueIndex(columns, name?)` — add an index.
+- `dropIndex(name)` — drop an index (runs before column drops).
+
+### `ForeignKeyBuilder`
+
+From `TableBuilder.foreign(column)`. Chainable: `references(column)`, `on(table)`,
+`onDelete(action)`, `onUpdate(action)`.
+
 ### `Column`
 
 A single column definition. **You get one from a `TableBuilder` method** (`t.string(...)` etc.) — you don't construct it in migrations. Modifier methods