@digimuza/saas-core 0.0.2

package/docs/email.md

@@ -0,0 +1,222 @@
+# Email
+
+```ts
+import {
+  createEmailService, createResendProvider, coreEmailTemplates,
+  defineEmailTemplates, emailTemplate, mergeEmailTemplates,
+} from "@digimuza/saas-core/email";
+```
+
+> Orientation and recipes: [`src/email/README.md`](../src/email/README.md).
+
+Provider-independent sending with typed templates. Everything above
+`EmailProvider` is generic, so adopting another provider means writing a ~20-line
+adapter.
+
+---
+
+## Setup
+
+```ts
+// lib/email.ts
+import { z } from "zod";
+import { config } from "@digimuza/saas-core/config";
+
+const templates = mergeEmailTemplates(
+  coreEmailTemplates,
+  defineEmailTemplates({
+    "project.shared": emailTemplate({
+      schema: z.object({ projectName: z.string().min(1), sharedBy: z.string().min(1) }),
+      subject: (data) => `${data.sharedBy} shared "${data.projectName}" with you`,
+      text: (data) => `${data.sharedBy} shared ${data.projectName}.`,
+      html: (data) => `<p>${data.sharedBy} shared ${data.projectName}.</p>`,
+    }),
+  }),
+);
+
+export const email = createEmailService({
+  provider: createResendProvider({ apiKey: config.email.apiKey }),
+  templates,
+  from: { address: config.email.fromAddress, name: config.email.fromName },
+  replyTo: { address: "support@acme.com" },
+});
+```
+
+`createConfiguredEmailProvider()` and `configuredSender()` build both from the
+`email` config section, choosing the console logger in development.
+
+### `emailTemplate()` is load-bearing
+
+TypeScript cannot infer a callback's parameter type from a **sibling** property of
+the same object literal. Writing a template inline leaves `data` as `unknown` in
+`subject` and `text`; binding the schema generic inside `emailTemplate()` is what
+types them.
+
+---
+
+## `email.sendTemplate(input)`
+
+```ts
+function sendTemplate(input: {
+  to: string | EmailAddress | readonly (string | EmailAddress)[];
+  template: K;                    // a key of the registry
+  data: z.input<T[K]["schema"]>;  // narrowed to that template
+  from?: EmailAddress;
+  replyTo?: string | EmailAddress;
+  idempotencyKey?: string;
+  headers?: Record<string, string>;
+}): Promise<SentEmail>
+```
+
+`data` is validated **before** a message is built, so a missing field throws
+`InvalidInputError` naming it rather than emailing a customer the word
+"undefined".
+
+## `email.send(input)`
+
+```ts
+function send(input: {
+  to: string | EmailAddress | readonly (string | EmailAddress)[];
+  subject: string;
+  text: string;                   // required
+  html?: string;                  // optional
+  from?: EmailAddress;
+  replyTo?: string | EmailAddress;
+  cc?: readonly (string | EmailAddress)[];
+  bcc?: readonly (string | EmailAddress)[];
+  idempotencyKey?: string;
+  headers?: Record<string, string>;
+}): Promise<SentEmail>
+```
+
+**A text part is mandatory; HTML is not.** Some clients render only text, and a
+text-less message scores worse with spam filters.
+
+Recipients accept a string, an object, or a list of either.
+
+## `email.render(template, data)`
+
+```ts
+function render<K>(template: K, data: z.input<T[K]["schema"]>):
+  { subject: string; text: string; html?: string }
+```
+
+Renders without sending — for previews, and for asserting copy in tests.
+
+---
+
+## Idempotency
+
+**Sending is not transactional with the database.** A retried request can send
+twice, and `idempotencyKey` is the only defence. Pass one for anything a customer
+would notice receiving twice.
+
+Resend honours it for 24 hours, via an `Idempotency-Key` header. A provider that
+ignores it will simply deliver twice — the interface cannot fix that.
+
+---
+
+## Templates
+
+### `defineEmailTemplates` / `mergeEmailTemplates` / `overrideEmailTemplates`
+
+`mergeEmailTemplates` **throws** on a duplicate key. `overrideEmailTemplates`
+replaces. Two functions, so shadowing a core template is a visible decision rather
+than silent:
+
+```ts
+const templates = overrideEmailTemplates(
+  coreEmailTemplates,
+  defineEmailTemplates({
+    "workspace.invitation": emailTemplate({ /* your branding */ }),
+  }),
+);
+```
+
+### What the core ships
+
+**One template: `workspace.invitation`.** It has to exist — the core creates
+invitations, and the single-use token cannot be delivered without an email.
+
+```ts
+{
+  workspaceName: string;
+  inviterName?: string;
+  acceptUrl: string;   // absolute, carries the token
+  expiresAt: Date;
+}
+```
+
+Its copy is intentionally plain. Override it for anything customer-facing.
+
+Welcome, security and billing emails are **not** shipped. They are product copy;
+a default would mean shipping branding decisions every application overrides
+anyway.
+
+---
+
+## Providers
+
+```ts
+interface EmailProvider {
+  readonly name: string;
+  send(message: OutgoingEmail): Promise<SentEmail>;
+}
+```
+
+One method, because sending is all the core needs. Bounce handling, suppression
+lists and analytics live in the provider's dashboard — wrapping them would mean
+maintaining a lowest common denominator of every provider's feature set.
+
+| Provider | Use |
+| --- | --- |
+| `createResendProvider({ apiKey })` | Production. **HTTP call unverified** against live credentials. |
+| `createConsoleEmailProvider()` | Development. Refuses to run in production. |
+| `createMemoryEmailProvider()` | Tests. Collects messages, dedupes on `idempotencyKey`. |
+
+### Writing your own
+
+```ts
+const provider: EmailProvider = {
+  name: "postmark",
+  async send(message) {
+    const response = await fetch("https://api.postmarkapp.com/email", {
+      method: "POST",
+      headers: { "X-Postmark-Server-Token": token, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        From: formatAddress(message.from),
+        To: message.to.map(formatAddress).join(","),
+        Subject: message.subject,
+        TextBody: message.text,
+        HtmlBody: message.html,
+      }),
+    });
+
+    // Do not include the response body: provider errors echo request contents,
+    // and a bounced address is personal data.
+    if (!response.ok) throw new Error(`Postmark rejected: ${response.status}`);
+
+    const body = (await response.json()) as { MessageID: string };
+    return { id: body.MessageID, provider: "postmark" };
+  },
+};
+```
+
+### `formatAddress(address)`
+
+Quotes the display name and strips embedded quotes, so a name containing a comma
+stays in one field and one containing a quote cannot split the header.
+
+---
+
+## Testing
+
+```ts
+const provider = createMemoryEmailProvider();
+const email = createEmailService({ provider, templates, from: { address: "a@b.test" } });
+
+await email.sendTemplate({ to: "user@example.test", template: "project.shared", data });
+
+expect(provider.to("user@example.test")).toHaveLength(1);
+expect(provider.sent[0]?.subject).toContain("shared");
+```

package/docs/entitlements.md

@@ -0,0 +1,194 @@
+# Entitlements
+
+```ts
+import { entitlements, createEntitlementsService } from "@digimuza/saas-core/entitlements";
+```
+
+> Orientation and recipes: [`src/entitlements/README.md`](../src/entitlements/README.md).
+
+
+What a workspace has *paid for*, as opposed to what a user is *allowed* to do.
+
+```
+Subscription → Plan → Entitlements → features and limits
+```
+
+**Product code must never inspect a plan name.** Ask about the entitlement.
+
+---
+
+## Two kinds of entitlement
+
+- **`feature`** — on or off. `ai_generation`, `api_access`, `custom_domains`.
+- **`limit`** — a quota. `ai_generations`, `team_members`, `storage_bytes`.
+
+Defined per plan; see [billing.md](./billing.md#plans).
+
+---
+
+## `entitlements.has(context, key)`
+
+```ts
+function has(context: WorkspaceContext, key: string): Promise<boolean>
+```
+
+Whether the workspace's plan includes this key at all.
+
+## `entitlements.require(context, key)`
+
+```ts
+function require(context: WorkspaceContext, key: string): Promise<void>
+```
+
+Throws `EntitlementRequiredError` (code `payment_required`, HTTP 402) with
+`.entitlement` set. Deliberately distinct from `ForbiddenError`: a client shows an
+upsell for this and an access error for that.
+
+## `entitlements.getLimit(context, key)`
+
+```ts
+function getLimit(context: WorkspaceContext, key: string): Promise<number | null>
+```
+
+Three states, all distinct:
+
+| Return | Meaning |
+| --- | --- |
+| `null` | Unlimited |
+| `0` | Explicitly none |
+| `0` | Key absent from the plan — **fails closed** |
+
+A limit the plan does not mention is zero, not unlimited. A typo in a plan
+definition must not hand out infinite quota. Asking for the limit of a *feature*
+also returns `0`, because it is a meaningless question.
+
+## `entitlements.checkLimit(context, key, quantity?)`
+
+```ts
+function checkLimit(context: WorkspaceContext, key: string, quantity = 1): Promise<LimitCheck>
+
+interface LimitCheck {
+  allowed: boolean;
+  limit: number | null;      // null = unlimited
+  used: number;
+  remaining: number | null;  // null = unlimited
+  window: { start: Date; end: Date };
+}
+```
+
+`remaining` never goes negative. `requireLimit` is the throwing variant
+(`LimitExceededError`, carrying `.limit` and `.used`).
+
+## `entitlements.getUsage(context, key)` / `recordUsage(...)`
+
+```ts
+function getUsage(context: WorkspaceContext, key: string): Promise<number>
+
+function recordUsage(context: WorkspaceContext, key: string, options?: {
+  quantity?: number;         // 1
+  idempotencyKey?: string;
+  occurredAt?: Date;
+}): Promise<void>
+```
+
+`recordUsage` does not itself enforce the limit. A reused `idempotencyKey` is
+counted **once**, so a network retry does not consume a customer's quota twice —
+scoped per workspace, since two tenants may legitimately use the same request id.
+
+## `entitlements.consume(context, key, options?)`
+
+```ts
+function consume(context: WorkspaceContext, key: string, options?: RecordUsageOptions): Promise<LimitCheck>
+```
+
+Check and record together. Throws `LimitExceededError` **without recording
+anything**.
+
+```ts
+await entitlements.consume(context, "ai_generations", {
+  quantity: 1,
+  idempotencyKey: requestId,
+});
+```
+
+### It is not transactional, on purpose
+
+The check and the insert are separate statements, so concurrent consumers can
+together overshoot the quota by their in-flight quantity. That is a deliberate
+trade: serialising every metered call behind a lock would make the hot path a
+contention point, and a small overshoot on a usage quota is cheaper than that.
+
+If you need a hard cap, wrap `consume` in your own transaction with
+`SELECT ... FOR UPDATE` on a per-workspace row.
+
+## `entitlements.resolve(context)` / `resolvePlan(context)`
+
+```ts
+function resolve(context: WorkspaceContext): Promise<{
+  plan: Plan | undefined;
+  byKey: ReadonlyMap<string, Entitlement>;
+}>
+function resolvePlan(context: WorkspaceContext): Promise<Plan | undefined>
+```
+
+Everything at once — for rendering a plan-comparison or usage page without a query
+per key.
+
+---
+
+## Which subscriptions entitle
+
+`trialing`, `active` and `past_due` all entitle. **`past_due` is a dunning state,
+not a revocation** — cutting access the moment a card fails is usually the wrong
+product decision, and the provider is still retrying.
+
+`paused`, `canceled` and `incomplete` do not entitle.
+
+Cancelling at period end keeps entitlements until the paid period ends; cancelling
+immediately ends them now. See [billing.md](./billing.md).
+
+---
+
+## The usage window
+
+Consumption is summed over a window, never all-time:
+
+1. The subscription's billing period, when it has one — that is what the customer
+   is paying for.
+2. Otherwise the current **UTC calendar month**.
+
+The fallback matters: a workspace on a free plan has no billing period, and an
+all-time total would leave a monthly quota permanently exhausted.
+
+Usage is append-only. A running counter would lose the ability to attribute usage
+to a period, and would make concurrent increments a contention point.
+
+---
+
+## Free tiers
+
+The default `entitlements` export configures **no fallback plan**, so a workspace
+without a live subscription has no entitlements at all. That is the safe default
+but leaves no room for a free tier. Build your own:
+
+```ts
+import { createEntitlementsService } from "@digimuza/saas-core/entitlements";
+import { getDatabase } from "@digimuza/saas-core/db";
+
+export const entitlements = createEntitlementsService({
+  db: getDatabase(),
+  fallbackPlanKey: "free",
+});
+```
+
+A live subscription always wins over the fallback.
+
+---
+
+## Testing
+
+```ts
+createEntitlementsService({ db, now: () => new Date("2026-06-15T12:00:00Z") });
+```
+
+Inject `now` to make calendar-month windows deterministic.

package/docs/errors.md

@@ -0,0 +1,158 @@
+# Errors
+
+```ts
+import {
+  SaasCoreError, UnauthorizedError, ForbiddenError, NotFoundError,
+  ConflictError, InvalidInputError, EntitlementRequiredError, LimitExceededError,
+} from "@digimuza/saas-core";
+
+// Identical, if you prefer the explicit subpath:
+import { NotFoundError } from "@digimuza/saas-core/errors";
+```
+
+Both entry points export the same classes. The root re-exports them because route
+handlers map errors to status codes and would otherwise need a second import just
+for the error types.
+
+Every core error carries a stable machine-readable `code`, so handlers map to
+status codes without matching on message text.
+
+| Error | `code` | Status | Meaning |
+| --- | --- | --- | --- |
+| `UnauthorizedError` | `unauthorized` | 401 | No authenticated user |
+| `ForbiddenError` | `forbidden` | 403 | Authenticated, lacks the permission |
+| `NotFoundError` | `not_found` | 404 | Absent, or the caller may not know it exists |
+| `ConflictError` | `conflict` | 409 | Conflicts with existing state |
+| `InvalidInputError` | `invalid_input` | 400 | Structurally invalid input |
+| `EntitlementRequiredError` | `payment_required` | 402 | Plan does not include the feature |
+| `LimitExceededError` | `limit_exceeded` | 429 | Metered quota exhausted |
+
+All extend `SaasCoreError`.
+
+---
+
+## Mapping to HTTP
+
+```ts
+import { SaasCoreError } from "@digimuza/saas-core";
+
+const STATUS: Record<string, number> = {
+  unauthorized: 401,
+  forbidden: 403,
+  not_found: 404,
+  conflict: 409,
+  invalid_input: 400,
+  payment_required: 402,
+  limit_exceeded: 429,
+};
+
+export function toResponse(error: unknown): Response {
+  if (error instanceof SaasCoreError) {
+    return Response.json(
+      { error: error.code, message: error.message },
+      { status: STATUS[error.code] ?? 500 },
+    );
+  }
+  throw error;   // let genuine faults become a 500 and reach your tracker
+}
+```
+
+---
+
+## Errors that carry detail
+
+```ts
+class ForbiddenError extends SaasCoreError {
+  readonly permission?: string;      // the permission that was required
+}
+
+class EntitlementRequiredError extends SaasCoreError {
+  readonly entitlement: string;
+}
+
+class LimitExceededError extends SaasCoreError {
+  readonly entitlement: string;
+  readonly limit: number;
+  readonly used: number;
+}
+```
+
+Enough to drive UI without parsing a message:
+
+```ts
+try {
+  await entitlements.consume(context, "ai_generations");
+} catch (error) {
+  if (error instanceof LimitExceededError) {
+    return upsell({ used: error.used, limit: error.limit });
+  }
+  throw error;
+}
+```
+
+---
+
+## Not found vs forbidden
+
+Tenant isolation reports **`NotFoundError`** for a workspace the caller is not a
+member of, not `ForbiddenError`.
+
+A 403 confirms that a given workspace id or slug *exists*, which lets an attacker
+enumerate other tenants by iterating ids. A 404 reveals nothing.
+
+`ForbiddenError` is for callers already known to belong to the workspace who lack a
+specific permission — inside the tenant boundary, where existence is not a secret.
+
+The same reasoning makes missing, expired, revoked and already-accepted invitation
+tokens all raise one indistinguishable `NotFoundError`: telling them apart would
+tell a token-guessing attacker which guesses hit.
+
+---
+
+## Forbidden vs payment required
+
+`ForbiddenError` means "you may not". `EntitlementRequiredError` means "your plan
+does not include this". Clients render an access error for the first and an upsell
+for the second, so conflating them produces the wrong UI.
+
+Both checks usually apply:
+
+```ts
+await authorization.require(context, "projects.create");   // 403 if not permitted
+await entitlements.require(context, "ai_generation");      // 402 if not paid for
+```
+
+---
+
+## Errors outside this hierarchy
+
+Some deliberately do not extend `SaasCoreError`:
+
+- **`ConfigError`** (`@digimuza/saas-core/config`) — a startup fault, not a request
+  outcome. Names the offending variables and never interpolates values, so a
+  malformed secret cannot leak into a log or error tracker.
+- **`InvalidWebhookSignatureError`** (`@digimuza/saas-core/billing`) — map it to
+  401 yourself. Its message is deliberately uninformative: a caller who cannot
+  produce a valid signature gets no hint about which part failed.
+
+---
+
+## Database constraint failures
+
+Services translate the constraint violations that represent domain outcomes:
+
+- duplicate workspace slug → `ConflictError`
+- outstanding invitation for that email → `ConflictError`
+- cross-workspace role assignment → `NotFoundError`
+
+Anything else propagates. That is intentional — swallowing an unrecognised
+constraint failure hides a real bug. If you catch these yourself, always match on
+the **constraint name**, not just the SQLSTATE code:
+
+```ts
+import { isUniqueViolation } from "@digimuza/saas-core/db";
+
+if (isUniqueViolation(error, "projects_workspace_id_name_unique")) { /* ... */ }
+```
+
+See [db.md](./db.md#constraint-error-introspection).