@digimuza/saas-core 0.0.2

package/docs/workspaces.md

@@ -0,0 +1,269 @@
+# Workspaces, members & invitations
+
+```ts
+import { workspaces } from "@digimuza/saas-core/workspaces";
+```
+
+> Orientation and recipes: [`src/workspaces/README.md`](../src/workspaces/README.md).
+
+
+A workspace is the tenancy boundary. Users belong to many workspaces through
+`workspace_members`; `workspace_id` never appears on `users`.
+
+---
+
+## `WorkspaceContext`
+
+```ts
+interface WorkspaceContext {
+  readonly userId: string;
+  readonly workspaceId: string;
+  readonly membershipVerified: true;
+}
+```
+
+**Every tenant-scoped operation in the core takes one of these**, and the only way
+to get one is a verified membership lookup. So a `workspaceId` read from a request
+body, query string or path parameter will not type-check where a context is
+required.
+
+The marker is a convention, not a cryptographic guarantee — but it makes bypassing
+the check a deliberate, greppable act rather than an oversight.
+
+```ts
+// The standard shape of a tenant-scoped handler.
+const user = await auth.requireUser();
+const context = await workspaces.requireContext({
+  userId: user.id,
+  workspaceId: params.workspaceId,   // untrusted until this call returns
+});
+await authorization.require(context, "projects.create");
+```
+
+## `workspaces.resolveContext(input)`
+
+```ts
+function resolveContext(input: { userId: string; workspaceId: string }):
+  Promise<WorkspaceContext | undefined>
+```
+
+Returns `undefined` when the user is not a member.
+
+## `workspaces.requireContext(input)`
+
+```ts
+function requireContext(input: { userId: string; workspaceId: string }): Promise<WorkspaceContext>
+```
+
+Throws **`NotFoundError`**, not `ForbiddenError`. A 403 would confirm that a given
+workspace id exists, letting an attacker enumerate tenants by iterating ids. See
+[errors.md](./errors.md#not-found-vs-forbidden).
+
+## `workspaces.requireContextBySlug(input)`
+
+```ts
+function requireContextBySlug(input: { userId: string; slug: string }): Promise<WorkspaceContext>
+```
+
+Same guarantee for URL-addressed workspaces. Resolves slug and membership in one
+query, so a non-member cannot distinguish "no such slug" from "not your workspace".
+
+---
+
+## `workspaces.create(input)`
+
+```ts
+function create(input: {
+  name: string;
+  slug?: string;                                  // derived from name if omitted
+  ownerUserId: string;
+  systemRoles?: readonly SystemRoleDefinition[];  // defaults to admin + member
+}): Promise<Workspace>
+```
+
+In one transaction: creates the workspace, seeds the system roles, adds the creator
+as a member, and grants them `admin`. Without that last step a new workspace would
+have nobody able to administer it.
+
+Throws `ConflictError` if the slug is taken, `InvalidInputError` if the name
+contains no alphanumeric character.
+
+```ts
+const workspace = await workspaces.create({
+  name: "Acme Corp",       // slug becomes "acme-corp"
+  ownerUserId: user.id,
+});
+```
+
+### Overriding the seeded roles
+
+```ts
+await workspaces.create({
+  name: "Acme",
+  ownerUserId: user.id,
+  systemRoles: [
+    { key: "admin", name: "Administrator" },
+    { key: "editor", name: "Editor", isDefault: true },
+    { key: "viewer", name: "Viewer" },
+  ],
+});
+```
+
+The creator gets `admin` if it exists, otherwise the default role, otherwise the
+first. Exactly one role may be `isDefault` per workspace — enforced by a partial
+unique index.
+
+## `workspaces.get` / `update` / `delete`
+
+```ts
+function get(context: WorkspaceContext): Promise<Workspace>
+function update(context: WorkspaceContext, patch: { name?: string; slug?: string }): Promise<Workspace>
+function delete(context: WorkspaceContext): Promise<void>
+```
+
+`update` emits `workspace.updated` listing which fields changed, so consumers can
+skip work they do not care about.
+
+## `workspaces.listForUser(userId)`
+
+```ts
+function listForUser(userId: string): Promise<Workspace[]>
+```
+
+Takes a raw user id rather than a context — this is the query that *builds* the
+workspace switcher, before any workspace is chosen.
+
+---
+
+## Members
+
+### `workspaces.members.list(context)`
+
+```ts
+function list(context: WorkspaceContext): Promise<WorkspaceMemberSummary[]>
+```
+
+```ts
+interface WorkspaceMemberSummary {
+  userId: string;
+  email: string | null;
+  displayName: string | null;
+  avatarUrl: string | null;
+  joinedAt: Date;
+  roles: readonly { id: string; key: string; name: string }[];
+}
+```
+
+One query returning member/role pairs, folded into one entry per member.
+
+### `workspaces.members.add(context, input)`
+
+```ts
+function add(context: WorkspaceContext, input: {
+  userId: string;
+  roleIds?: readonly string[];   // defaults to the workspace default role
+}): Promise<void>
+```
+
+Direct addition, bypassing the invitation flow — for admin tooling and for users
+who already exist. Idempotent.
+
+### `workspaces.members.remove(context, userId)`
+
+```ts
+function remove(context: WorkspaceContext, userId: string): Promise<void>
+```
+
+Deletes first, then counts what is left, inside one transaction. Throws
+`ConflictError` if that would empty the workspace, and `NotFoundError` if the user
+is not a member of *this* workspace.
+
+The order matters. Counting first was a real bug: it reported "last member" for
+someone who was not a member at all — leaking the workspace's member count to an
+outsider — and it raced, since two concurrent removals could each see two members
+and both proceed.
+
+Role grants cascade away via `workspace_member_roles_member_fk`.
+
+---
+
+## Invitations
+
+### `workspaces.members.invite(context, input)`
+
+```ts
+function invite(context: WorkspaceContext, input: {
+  email: string;
+  roleId?: string;              // falls back to the workspace default role
+  expiresInSeconds?: number;    // 7 days
+}): Promise<{ invitation: WorkspaceInvitation; token: string }>
+```
+
+```ts
+const { invitation, token } = await workspaces.members.invite(context, {
+  email: "new@example.com",
+});
+await email.send({ to: invitation.email, token });   // the only chance to use it
+```
+
+**`token` is returned once.** Only its SHA-256 hash is stored, so a database leak
+does not let an attacker accept outstanding invitations. Lose the token and you
+must revoke and re-issue.
+
+Throws `ConflictError` if an invitation for that address is already outstanding —
+a partial unique index allows one *pending* invitation per email per workspace
+while keeping accepted and revoked history queryable. Email is lowercased so the
+index behaves predictably.
+
+Throws `InvalidInputError` for a malformed address.
+
+### `workspaces.members.acceptInvitation(input)`
+
+```ts
+function acceptInvitation(input: { token: string; userId: string }): Promise<WorkspaceContext>
+```
+
+Not workspace-scoped: the token identifies the workspace. `userId` must be the
+**authenticated** user, never taken from the invitation payload.
+
+Returns a verified context, so the caller can immediately act as the new member.
+
+Missing, expired, revoked and already-accepted tokens all raise the **same**
+`NotFoundError` with the same message. Distinguishing them would tell a
+token-guessing attacker which guesses corresponded to real invitations.
+
+Acceptance re-checks the guard in its `UPDATE ... WHERE`, so two concurrent
+redemptions cannot both succeed.
+
+### `listInvitations` / `revokeInvitation`
+
+```ts
+function listInvitations(context: WorkspaceContext): Promise<WorkspaceInvitation[]>
+function revokeInvitation(context: WorkspaceContext, invitationId: string): Promise<void>
+```
+
+`listInvitations` returns only outstanding ones. `revokeInvitation` is scoped to the
+caller's workspace, so an id from another tenant matches nothing and raises
+`NotFoundError`.
+
+---
+
+## `slugify(value)`
+
+```ts
+function slugify(value: string): string
+```
+
+Normalises Unicode, strips diacritics, lowercases, collapses non-alphanumerics to
+hyphens, caps at 60 characters. Throws `InvalidInputError` if nothing usable
+remains.
+
+---
+
+## Custom construction
+
+```ts
+import { createWorkspacesService } from "@digimuza/saas-core/workspaces";
+
+const workspaces = createWorkspacesService({ db, events });   // events optional
+```

package/drizzle/0000_init_users.sql

@@ -0,0 +1,21 @@
+CREATE TABLE "user_profiles" (
+	"user_id" uuid PRIMARY KEY NOT NULL,
+	"email" text NOT NULL,
+	"first_name" text,
+	"last_name" text,
+	"display_name" text,
+	"avatar_url" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "users" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"workos_user_id" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "users_workos_user_id_unique" UNIQUE("workos_user_id")
+);
+--> statement-breakpoint
+ALTER TABLE "user_profiles" ADD CONSTRAINT "user_profiles_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "user_profiles_email_lower_idx" ON "user_profiles" USING btree (lower("email"));

package/drizzle/0001_workspaces_roles_permissions.sql

@@ -0,0 +1,86 @@
+CREATE TABLE "workspace_members" (
+	"workspace_id" uuid NOT NULL,
+	"user_id" uuid NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "workspace_members_workspace_id_user_id_pk" PRIMARY KEY("workspace_id","user_id")
+);
+--> statement-breakpoint
+CREATE TABLE "workspaces" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"slug" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "workspaces_slug_unique" UNIQUE("slug")
+);
+--> statement-breakpoint
+CREATE TABLE "permissions" (
+	"key" text PRIMARY KEY NOT NULL,
+	"description" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "role_permissions" (
+	"role_id" uuid NOT NULL,
+	"permission_key" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "role_permissions_role_id_permission_key_pk" PRIMARY KEY("role_id","permission_key")
+);
+--> statement-breakpoint
+CREATE TABLE "roles" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"workspace_id" uuid NOT NULL,
+	"key" text NOT NULL,
+	"name" text NOT NULL,
+	"description" text,
+	"is_system" boolean DEFAULT false NOT NULL,
+	"is_default" boolean DEFAULT false NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "roles_id_workspace_id_key" UNIQUE("id","workspace_id")
+);
+--> statement-breakpoint
+CREATE TABLE "workspace_member_roles" (
+	"workspace_id" uuid NOT NULL,
+	"user_id" uuid NOT NULL,
+	"role_id" uuid NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "workspace_member_roles_workspace_id_user_id_role_id_pk" PRIMARY KEY("workspace_id","user_id","role_id")
+);
+--> statement-breakpoint
+CREATE TABLE "workspace_invitations" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"workspace_id" uuid NOT NULL,
+	"email" text NOT NULL,
+	"token_hash" text NOT NULL,
+	"invited_by_user_id" uuid,
+	"role_id" uuid,
+	"expires_at" timestamp with time zone NOT NULL,
+	"accepted_at" timestamp with time zone,
+	"revoked_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "workspace_invitations_token_hash_unique" UNIQUE("token_hash")
+);
+--> statement-breakpoint
+ALTER TABLE "workspace_members" ADD CONSTRAINT "workspace_members_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_members" ADD CONSTRAINT "workspace_members_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "role_permissions" ADD CONSTRAINT "role_permissions_role_id_roles_id_fk" FOREIGN KEY ("role_id") REFERENCES "public"."roles"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "role_permissions" ADD CONSTRAINT "role_permissions_permission_key_permissions_key_fk" FOREIGN KEY ("permission_key") REFERENCES "public"."permissions"("key") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "roles" ADD CONSTRAINT "roles_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_member_roles" ADD CONSTRAINT "workspace_member_roles_member_fk" FOREIGN KEY ("workspace_id","user_id") REFERENCES "public"."workspace_members"("workspace_id","user_id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_member_roles" ADD CONSTRAINT "workspace_member_roles_role_fk" FOREIGN KEY ("role_id","workspace_id") REFERENCES "public"."roles"("id","workspace_id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_invitations" ADD CONSTRAINT "workspace_invitations_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_invitations" ADD CONSTRAINT "workspace_invitations_invited_by_user_id_users_id_fk" FOREIGN KEY ("invited_by_user_id") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_invitations" ADD CONSTRAINT "workspace_invitations_role_fk" FOREIGN KEY ("role_id","workspace_id") REFERENCES "public"."roles"("id","workspace_id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "workspace_members_user_id_idx" ON "workspace_members" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "role_permissions_permission_key_idx" ON "role_permissions" USING btree ("permission_key");--> statement-breakpoint
+CREATE UNIQUE INDEX "roles_workspace_id_key_idx" ON "roles" USING btree ("workspace_id","key");--> statement-breakpoint
+CREATE UNIQUE INDEX "roles_workspace_default_idx" ON "roles" USING btree ("workspace_id") WHERE "roles"."is_default";--> statement-breakpoint
+CREATE INDEX "workspace_member_roles_role_id_idx" ON "workspace_member_roles" USING btree ("role_id");--> statement-breakpoint
+CREATE INDEX "workspace_invitations_workspace_id_idx" ON "workspace_invitations" USING btree ("workspace_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "workspace_invitations_pending_idx" ON "workspace_invitations" USING btree ("workspace_id",lower("email")) WHERE "workspace_invitations"."accepted_at" is null and "workspace_invitations"."revoked_at" is null;

package/drizzle/0002_billing_entitlements.sql

@@ -0,0 +1,97 @@
+CREATE TYPE "public"."billing_event_status" AS ENUM('pending', 'processed', 'failed', 'ignored');--> statement-breakpoint
+CREATE TYPE "public"."billing_interval" AS ENUM('month', 'year', 'one_time');--> statement-breakpoint
+CREATE TYPE "public"."entitlement_kind" AS ENUM('feature', 'limit');--> statement-breakpoint
+CREATE TYPE "public"."subscription_status" AS ENUM('trialing', 'active', 'past_due', 'paused', 'canceled', 'incomplete');--> statement-breakpoint
+CREATE TABLE "billing_customers" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"workspace_id" uuid NOT NULL,
+	"provider" text NOT NULL,
+	"provider_customer_id" text NOT NULL,
+	"email" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "billing_customers_workspace_id_unique" UNIQUE("workspace_id"),
+	CONSTRAINT "billing_customers_provider_customer_unique" UNIQUE("provider","provider_customer_id")
+);
+--> statement-breakpoint
+CREATE TABLE "billing_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"provider" text NOT NULL,
+	"provider_event_id" text NOT NULL,
+	"type" text NOT NULL,
+	"payload" jsonb NOT NULL,
+	"status" "billing_event_status" DEFAULT 'pending' NOT NULL,
+	"processed_at" timestamp with time zone,
+	"error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "billing_events_provider_event_unique" UNIQUE("provider","provider_event_id")
+);
+--> statement-breakpoint
+CREATE TABLE "entitlements" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"plan_id" uuid NOT NULL,
+	"key" text NOT NULL,
+	"kind" "entitlement_kind" NOT NULL,
+	"limit_value" bigint,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "entitlements_plan_id_key_unique" UNIQUE("plan_id","key")
+);
+--> statement-breakpoint
+CREATE TABLE "plans" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"key" text NOT NULL,
+	"name" text NOT NULL,
+	"description" text,
+	"provider_price_id" text,
+	"amount_cents" integer DEFAULT 0 NOT NULL,
+	"currency" text DEFAULT 'EUR' NOT NULL,
+	"interval" "billing_interval" DEFAULT 'month' NOT NULL,
+	"is_active" boolean DEFAULT true NOT NULL,
+	"sort_order" integer DEFAULT 0 NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "plans_key_unique" UNIQUE("key")
+);
+--> statement-breakpoint
+CREATE TABLE "subscriptions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"workspace_id" uuid NOT NULL,
+	"billing_customer_id" uuid NOT NULL,
+	"plan_id" uuid NOT NULL,
+	"provider" text NOT NULL,
+	"provider_subscription_id" text NOT NULL,
+	"status" "subscription_status" NOT NULL,
+	"current_period_start" timestamp with time zone,
+	"current_period_end" timestamp with time zone,
+	"cancel_at_period_end" boolean DEFAULT false NOT NULL,
+	"canceled_at" timestamp with time zone,
+	"trial_ends_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "subscriptions_provider_subscription_unique" UNIQUE("provider","provider_subscription_id")
+);
+--> statement-breakpoint
+CREATE TABLE "usage_records" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"workspace_id" uuid NOT NULL,
+	"key" text NOT NULL,
+	"quantity" integer DEFAULT 1 NOT NULL,
+	"occurred_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"idempotency_key" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "billing_customers" ADD CONSTRAINT "billing_customers_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "entitlements" ADD CONSTRAINT "entitlements_plan_id_plans_id_fk" FOREIGN KEY ("plan_id") REFERENCES "public"."plans"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_billing_customer_id_billing_customers_id_fk" FOREIGN KEY ("billing_customer_id") REFERENCES "public"."billing_customers"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_plan_id_plans_id_fk" FOREIGN KEY ("plan_id") REFERENCES "public"."plans"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "usage_records" ADD CONSTRAINT "usage_records_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "billing_events_status_idx" ON "billing_events" USING btree ("status");--> statement-breakpoint
+CREATE INDEX "plans_is_active_idx" ON "plans" USING btree ("is_active");--> statement-breakpoint
+CREATE INDEX "subscriptions_workspace_id_idx" ON "subscriptions" USING btree ("workspace_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "subscriptions_one_live_per_workspace_idx" ON "subscriptions" USING btree ("workspace_id") WHERE "subscriptions"."status" in ('trialing', 'active', 'past_due');--> statement-breakpoint
+CREATE INDEX "usage_records_workspace_key_occurred_idx" ON "usage_records" USING btree ("workspace_id","key","occurred_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "usage_records_idempotency_idx" ON "usage_records" USING btree ("workspace_id","key","idempotency_key") WHERE "usage_records"."idempotency_key" is not null;

package/drizzle/0003_events.sql

@@ -0,0 +1,17 @@
+CREATE TABLE "events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"type" text NOT NULL,
+	"workspace_id" uuid,
+	"actor_user_id" uuid,
+	"data" jsonb NOT NULL,
+	"occurred_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"idempotency_key" text
+);
+--> statement-breakpoint
+ALTER TABLE "events" ADD CONSTRAINT "events_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "events" ADD CONSTRAINT "events_actor_user_id_users_id_fk" FOREIGN KEY ("actor_user_id") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "events_workspace_occurred_idx" ON "events" USING btree ("workspace_id","occurred_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE INDEX "events_type_occurred_idx" ON "events" USING btree ("type","occurred_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE INDEX "events_actor_idx" ON "events" USING btree ("actor_user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "events_idempotency_idx" ON "events" USING btree ("type","idempotency_key") WHERE "events"."idempotency_key" is not null;

package/drizzle/0004_notifications_audit.sql

@@ -0,0 +1,64 @@
+CREATE TABLE "audit_logs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"actor_user_id" uuid,
+	"workspace_id" uuid,
+	"action" text NOT NULL,
+	"target_type" text,
+	"target_id" text,
+	"metadata" jsonb,
+	"request_id" text,
+	"ip_address" text,
+	"user_agent" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "notifications" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" uuid NOT NULL,
+	"workspace_id" uuid,
+	"type" text NOT NULL,
+	"title" text NOT NULL,
+	"body" text,
+	"url" text,
+	"data" jsonb,
+	"read_at" timestamp with time zone,
+	"dedupe_key" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "notifications" ADD CONSTRAINT "notifications_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "notifications" ADD CONSTRAINT "notifications_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "audit_logs_workspace_created_idx" ON "audit_logs" USING btree ("workspace_id","created_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE INDEX "audit_logs_actor_created_idx" ON "audit_logs" USING btree ("actor_user_id","created_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE INDEX "audit_logs_action_created_idx" ON "audit_logs" USING btree ("action","created_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE INDEX "audit_logs_target_idx" ON "audit_logs" USING btree ("target_type","target_id");--> statement-breakpoint
+CREATE INDEX "notifications_user_unread_idx" ON "notifications" USING btree ("user_id","read_at","created_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE INDEX "notifications_workspace_idx" ON "notifications" USING btree ("workspace_id","created_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE UNIQUE INDEX "notifications_dedupe_idx" ON "notifications" USING btree ("user_id","type","dedupe_key") WHERE "notifications"."dedupe_key" is not null;
+
+--> statement-breakpoint
+-- Audit immutability, enforced by PostgreSQL rather than by convention.
+--
+-- The service exposes no update or delete, but a trail that depends on
+-- application discipline is not a trail: a migration, a data repair, or a psql
+-- session would silently rewrite history. This rejects both operations outright,
+-- so amending an entry requires deliberately dropping the trigger first — which
+-- is itself an auditable act.
+--
+-- This is also why audit_logs carries no foreign keys. `ON DELETE SET NULL` is an
+-- UPDATE, so a referencing audit row would make its own subject undeletable.
+CREATE OR REPLACE FUNCTION saas_core_audit_logs_immutable()
+RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION
+    'audit_logs is append-only: % is not permitted', TG_OP
+    USING ERRCODE = 'restrict_violation';
+END;
+$$ LANGUAGE plpgsql;--> statement-breakpoint
+CREATE TRIGGER audit_logs_no_update
+  BEFORE UPDATE ON "audit_logs"
+  FOR EACH ROW EXECUTE FUNCTION saas_core_audit_logs_immutable();--> statement-breakpoint
+CREATE TRIGGER audit_logs_no_delete
+  BEFORE DELETE ON "audit_logs"
+  FOR EACH ROW EXECUTE FUNCTION saas_core_audit_logs_immutable();

package/drizzle/0005_api_keys_webhooks.sql

@@ -0,0 +1,77 @@
+CREATE TYPE "public"."inbound_webhook_status" AS ENUM('pending', 'processed', 'failed', 'ignored');--> statement-breakpoint
+CREATE TYPE "public"."webhook_delivery_status" AS ENUM('pending', 'succeeded', 'failed', 'exhausted');--> statement-breakpoint
+CREATE TABLE "api_keys" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"workspace_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"key_id" text NOT NULL,
+	"key_hash" text NOT NULL,
+	"scopes" text[] DEFAULT '{}'::text[] NOT NULL,
+	"created_by_user_id" uuid,
+	"last_used_at" timestamp with time zone,
+	"expires_at" timestamp with time zone,
+	"revoked_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "api_keys_key_id_unique" UNIQUE("key_id")
+);
+--> statement-breakpoint
+CREATE TABLE "inbound_webhooks" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"source" text NOT NULL,
+	"external_id" text NOT NULL,
+	"type" text NOT NULL,
+	"payload" jsonb NOT NULL,
+	"workspace_id" uuid,
+	"status" "inbound_webhook_status" DEFAULT 'pending' NOT NULL,
+	"processed_at" timestamp with time zone,
+	"error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "inbound_webhooks_source_external_unique" UNIQUE("source","external_id")
+);
+--> statement-breakpoint
+CREATE TABLE "webhook_deliveries" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"endpoint_id" uuid NOT NULL,
+	"event_id" uuid NOT NULL,
+	"event_type" text NOT NULL,
+	"payload" jsonb NOT NULL,
+	"status" "webhook_delivery_status" DEFAULT 'pending' NOT NULL,
+	"attempt_count" integer DEFAULT 0 NOT NULL,
+	"next_attempt_at" timestamp with time zone,
+	"last_attempted_at" timestamp with time zone,
+	"response_status" integer,
+	"error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "webhook_deliveries_endpoint_event_unique" UNIQUE("endpoint_id","event_id")
+);
+--> statement-breakpoint
+CREATE TABLE "webhook_endpoints" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"workspace_id" uuid NOT NULL,
+	"url" text NOT NULL,
+	"description" text,
+	"secret" text NOT NULL,
+	"event_types" text[] DEFAULT '{}'::text[] NOT NULL,
+	"is_active" boolean DEFAULT true NOT NULL,
+	"consecutive_failures" integer DEFAULT 0 NOT NULL,
+	"disabled_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "webhook_endpoints_workspace_url_unique" UNIQUE("workspace_id","url")
+);
+--> statement-breakpoint
+ALTER TABLE "api_keys" ADD CONSTRAINT "api_keys_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "api_keys" ADD CONSTRAINT "api_keys_created_by_user_id_users_id_fk" FOREIGN KEY ("created_by_user_id") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "inbound_webhooks" ADD CONSTRAINT "inbound_webhooks_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "webhook_deliveries" ADD CONSTRAINT "webhook_deliveries_endpoint_id_webhook_endpoints_id_fk" FOREIGN KEY ("endpoint_id") REFERENCES "public"."webhook_endpoints"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "webhook_deliveries" ADD CONSTRAINT "webhook_deliveries_event_id_events_id_fk" FOREIGN KEY ("event_id") REFERENCES "public"."events"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "webhook_endpoints" ADD CONSTRAINT "webhook_endpoints_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "api_keys_workspace_idx" ON "api_keys" USING btree ("workspace_id","created_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE INDEX "inbound_webhooks_status_idx" ON "inbound_webhooks" USING btree ("status");--> statement-breakpoint
+CREATE INDEX "inbound_webhooks_source_idx" ON "inbound_webhooks" USING btree ("source","created_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE INDEX "webhook_deliveries_due_idx" ON "webhook_deliveries" USING btree ("status","next_attempt_at");--> statement-breakpoint
+CREATE INDEX "webhook_deliveries_endpoint_idx" ON "webhook_deliveries" USING btree ("endpoint_id","created_at" DESC NULLS LAST);--> statement-breakpoint
+CREATE INDEX "webhook_endpoints_workspace_idx" ON "webhook_endpoints" USING btree ("workspace_id");

package/drizzle/0006_feature_flags.sql

@@ -0,0 +1,22 @@
+CREATE TYPE "public"."feature_flag_scope" AS ENUM('global', 'application', 'workspace', 'user');--> statement-breakpoint
+CREATE TABLE "feature_flags" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"key" text NOT NULL,
+	"scope" "feature_flag_scope" NOT NULL,
+	"application" text,
+	"workspace_id" uuid,
+	"user_id" uuid,
+	"enabled" boolean NOT NULL,
+	"variant" text,
+	"rollout_percentage" integer,
+	"description" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "feature_flags_target_unique" UNIQUE NULLS NOT DISTINCT("key","scope","application","workspace_id","user_id")
+);
+--> statement-breakpoint
+ALTER TABLE "feature_flags" ADD CONSTRAINT "feature_flags_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "feature_flags" ADD CONSTRAINT "feature_flags_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "feature_flags_key_scope_idx" ON "feature_flags" USING btree ("key","scope");--> statement-breakpoint
+CREATE INDEX "feature_flags_workspace_idx" ON "feature_flags" USING btree ("workspace_id");--> statement-breakpoint
+CREATE INDEX "feature_flags_user_idx" ON "feature_flags" USING btree ("user_id");