@palbase/backend 39.0.0 → 39.1.1

package/docs/auth.md

@@ -5,6 +5,26 @@ unless it opts out with `auth: false`. Client SDKs attach the user's token
 automatically, so on the backend you declare what a route needs and inject the
 user.
 
+## Temporary verification failures
+
+An absent or invalid access token produces `401 unauthorized` on a protected
+route. If the runtime cannot retrieve a usable signing keyset, it instead
+returns `503 auth_unavailable`. A network failure, an unsuccessful JWKS response,
+or a keyset with no usable signing keys is an availability failure, not evidence
+that the caller's token is invalid. Keep the session and retry after the service
+recovers; signing in again is not required while the token remains valid.
+
+The same rule applies to upload authorization. Requests that cannot be verified
+do not reach the handler or the database, and uploads receive no grant. Public
+requests without credentials continue to work.
+
+Known signing keys remain usable within their trust TTL (five minutes by
+default). Expired keysets are not trusted during an outage. Concurrent refreshes
+share one request, and failed refreshes and unknown key IDs share a one-second
+retry interval so recovery and key rotation do not wait for the entire TTL.
+
+## Declaring authentication
+
 ```ts
 import { Controller, Get, Post, Body, User, OptionalUser } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";

package/docs/database.md

@@ -29,6 +29,56 @@ await Database.public.todos.delete(todo.id);
 
 See [schema.md](./schema.md) for the full typed-table surface.
 
+## Tenant-scoped CRUD — `defineRepository`
+
+Most repository classes are the same two lines per method: add the tenant column
+to the predicate, then unwrap the result. Writing that by hand is what makes it
+forgettable, and one forgotten predicate shows one tenant's row to another.
+`defineRepository` produces a BASE CLASS that writes the predicate once.
+
+```ts
+import { defineRepository } from "@palbase/backend";
+
+export class TodoRepository extends defineRepository(
+  Database.public.todos,
+  { tenant: "household_id" },
+) {}
+```
+
+The subclass gets six typed methods, all scoped to the tenant you pass first:
+`list(tenant)`, `find(tenant, id)`, `insert(tenant, values)`,
+`update(tenant, id, patch)`, `updateScoped(tenant, id, patch)` and
+`delete(tenant, id)`. Add your own methods in the subclass body as usual.
+
+`insert` does NOT take the tenant column in its payload — the repository writes
+it. `update` throws `NotFound` when nothing matches, so the caller does not need
+a `null` branch; `updateScoped` runs the same predicate and returns `null`
+instead, for when absence is a value.
+
+The base class constructor takes no arguments, so the DI container resolves the
+subclass by its own name with no extra metadata. `Database` stays ambient rather
+than injected: it is request-scoped, so a reference captured in a constructor
+would carry one request's client into another.
+
+### A row key that is not `id`
+
+The row key defaults to `id`, but it is not fixed — `defineTable` does not
+require an `id` column, and a primary key can sit on any column. Name it:
+
+```ts
+export class DocRepository extends defineRepository(
+  Database.public.docs,
+  { tenant: "org_id", key: "slug" },
+) {}
+
+await new DocRepository().find("org_1", "getting-started");
+```
+
+The key parameter carries the column's OWN type, so a numeric key is typed
+`number` rather than assumed to be a string. If the table has no `id` column and
+you do not name a key, the surface refuses at compile time and the refusal says
+what to do (`MissingRowKey`).
+
 ## Transaction boundaries and retries
 
 Ordinary Database writes commit when the request completes. `$transaction(fn)`

package/docs/llms-full.txt

@@ -795,6 +795,26 @@ unless it opts out with `auth: false`. Client SDKs attach the user's token
 automatically, so on the backend you declare what a route needs and inject the
 user.
 
+## Temporary verification failures
+
+An absent or invalid access token produces `401 unauthorized` on a protected
+route. If the runtime cannot retrieve a usable signing keyset, it instead
+returns `503 auth_unavailable`. A network failure, an unsuccessful JWKS response,
+or a keyset with no usable signing keys is an availability failure, not evidence
+that the caller's token is invalid. Keep the session and retry after the service
+recovers; signing in again is not required while the token remains valid.
+
+The same rule applies to upload authorization. Requests that cannot be verified
+do not reach the handler or the database, and uploads receive no grant. Public
+requests without credentials continue to work.
+
+Known signing keys remain usable within their trust TTL (five minutes by
+default). Expired keysets are not trusted during an outage. Concurrent refreshes
+share one request, and failed refreshes and unknown key IDs share a one-second
+retry interval so recovery and key rotation do not wait for the entire TTL.
+
+## Declaring authentication
+
 ```ts
 import { Controller, Get, Post, Body, User, OptionalUser } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
@@ -1163,6 +1183,56 @@ await Database.public.todos.delete(todo.id);
 
 See [schema.md](./schema.md) for the full typed-table surface.
 
+## Tenant-scoped CRUD — `defineRepository`
+
+Most repository classes are the same two lines per method: add the tenant column
+to the predicate, then unwrap the result. Writing that by hand is what makes it
+forgettable, and one forgotten predicate shows one tenant's row to another.
+`defineRepository` produces a BASE CLASS that writes the predicate once.
+
+```ts
+import { defineRepository } from "@palbase/backend";
+
+export class TodoRepository extends defineRepository(
+  Database.public.todos,
+  { tenant: "household_id" },
+) {}
+```
+
+The subclass gets six typed methods, all scoped to the tenant you pass first:
+`list(tenant)`, `find(tenant, id)`, `insert(tenant, values)`,
+`update(tenant, id, patch)`, `updateScoped(tenant, id, patch)` and
+`delete(tenant, id)`. Add your own methods in the subclass body as usual.
+
+`insert` does NOT take the tenant column in its payload — the repository writes
+it. `update` throws `NotFound` when nothing matches, so the caller does not need
+a `null` branch; `updateScoped` runs the same predicate and returns `null`
+instead, for when absence is a value.
+
+The base class constructor takes no arguments, so the DI container resolves the
+subclass by its own name with no extra metadata. `Database` stays ambient rather
+than injected: it is request-scoped, so a reference captured in a constructor
+would carry one request's client into another.
+
+### A row key that is not `id`
+
+The row key defaults to `id`, but it is not fixed — `defineTable` does not
+require an `id` column, and a primary key can sit on any column. Name it:
+
+```ts
+export class DocRepository extends defineRepository(
+  Database.public.docs,
+  { tenant: "org_id", key: "slug" },
+) {}
+
+await new DocRepository().find("org_1", "getting-started");
+```
+
+The key parameter carries the column's OWN type, so a numeric key is typed
+`number` rather than assumed to be a string. If the table has no `id` column and
+you do not name a key, the surface refuses at compile time and the refusal says
+what to do (`MissingRowKey`).
+
 ## Transaction boundaries and retries
 
 Ordinary Database writes commit when the request completes. `$transaction(fn)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "39.0.0",
+  "version": "39.1.1",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {