@digimuza/saas-core 0.0.2

package/docs/files.md

@@ -0,0 +1,229 @@
+# Files
+
+```ts
+import { files, createFilesService } from "@digimuza/saas-core/files";
+```
+
+> Orientation and recipes: [`src/files/README.md`](../src/files/README.md).
+
+The durable record of a stored object. Pairs with [storage](./storage.md), which
+moves bytes and knows nothing about rows.
+
+---
+
+## Why the record is separate from the bytes
+
+Direct browser uploads make it necessary. The server issues a presigned URL and the
+client sends the bytes out-of-band, so:
+
+1. A row must exist **before** anything is stored — to reserve an id, derive a key,
+   and record intent.
+2. Something must **confirm** afterwards, because the server never sees the
+   transfer.
+
+Hence `status`: `pending` → `ready`, or `failed`.
+
+## The core owns the record, not the association
+
+A product table references `files.id` to say what a file is *for*:
+
+```ts
+export const documents = pgTable("documents", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  fileId: uuid("file_id").notNull().references(() => files.id, { onDelete: "cascade" }),
+  title: text("title").notNull(),
+});
+```
+
+A core table could not know whether a file is an avatar, an import or an
+attachment, so it does not try.
+
+---
+
+## Direct browser upload
+
+### `files.createUpload(context, input)`
+
+```ts
+function createUpload(context: WorkspaceContext, input: {
+  filename: string;
+  contentType?: string;
+  sizeBytes?: number;        // advisory — see below
+  metadata?: Record<string, unknown>;
+  expiresInSeconds?: number; // default 900
+  maxBytes?: number;
+}): Promise<{ file: FileRecord; uploadUrl: string }>
+```
+
+Creates a `pending` row and returns a URL the browser can `PUT` to.
+
+**The storage key is derived from the row id**, which is why the row is inserted
+first. So a filename never becomes part of a path:
+
+```ts
+const { file } = await files.createUpload(context, { filename: "../../etc/passwd" });
+file.storageKey;   // workspaces/<id>/files/<uuid>
+file.filename;     // "passwd"
+```
+
+`sizeBytes` only avoids issuing a URL for something obviously too big — a presigned
+`PUT` cannot enforce a size.
+
+`fileStoragePath(fileId)` is the mapping — `files/<id>` — exported so a migration
+or a reconciliation script can compute a key from a row without going through the
+service.
+
+### `files.confirmUpload(context, fileId)`
+
+```ts
+function confirmUpload(context: WorkspaceContext, fileId: string): Promise<FileRecord>
+```
+
+**Asks the store.** A client reporting success is not evidence: without this you
+could mark a file ready that was never uploaded, and every consumer downstream
+would fail on a missing object.
+
+| Outcome | Result |
+| --- | --- |
+| Object present, within limit | `ready`, with the store's **true** size |
+| No object | row `failed`, throws `ConflictError` |
+| Object over the limit | object **deleted**, row `failed`, throws `InvalidInputError` |
+| Already `ready` | returned unchanged — idempotent |
+
+Deleting an oversized object matters: leaving it would keep billing for bytes
+nothing can reach.
+
+It also backfills `contentType` from the store when the client declared none.
+
+Uses the provider's optional `stat()`. A provider without it falls back to
+`exists()`, which confirms presence but cannot verify size.
+
+---
+
+## Server-side upload
+
+### `files.upload(context, input)`
+
+```ts
+function upload(context: WorkspaceContext, input: {
+  filename: string;
+  body: Uint8Array | string;
+  contentType?: string;
+  metadata?: Record<string, unknown>;
+  maxBytes?: number;
+}): Promise<FileRecord>
+```
+
+One step, `ready` immediately — and with a **checksum**, because the server saw the
+bytes. A direct upload has no checksum for exactly that reason.
+
+If the store rejects the write, the row is **deleted** rather than left `pending`:
+a failed server-side upload leaves no object, so a reservation would be pure noise
+in the sweep.
+
+### `files.findByChecksum(context, checksum)`
+
+Deduplication. Scoped to the workspace, and only matches `ready` files.
+
+---
+
+## Reading, listing, deleting
+
+```ts
+files.get(context, fileId): Promise<FileRecord>
+files.list(context, options?): Promise<FileRecord[]>
+files.getUrl(context, fileId, options?): Promise<string>
+files.delete(context, fileId): Promise<void>
+```
+
+`list` filters by `status` (one or several), paginates with `before`, defaults to 50
+and caps at 200. Newest first, tie-broken on id so keyset pagination cannot loop.
+
+`getUrl` defaults `downloadFilename` to the stored filename, so a download is named
+sensibly and served as an **attachment** — which is what makes user uploads safe to
+hand back. See [storage](./storage.md#urls). It throws `ConflictError` for a file
+that is not `ready`, because there is no object behind it and the URL would 404.
+
+`delete` removes the **object first, then the row**. The other order would orphan
+the object on failure: unreachable, and still billed. There is a test asserting the
+row survives when the store delete fails.
+
+Every method takes a verified `WorkspaceContext` and scopes on it, so another
+tenant's file id is simply not found.
+
+---
+
+## `files.purgeAbandoned(options?)`
+
+```ts
+function purgeAbandoned(options?: { olderThan?: Date; limit?: number }): Promise<number>
+```
+
+A presigned URL that is never used leaves a `pending` row forever. Run this from a
+scheduled job:
+
+```ts
+export const sweepFiles = schedules.task({
+  id: "sweep-files",
+  cron: "0 * * * *",
+  run: () => files.purgeAbandoned(),
+});
+```
+
+Deletes the object unconditionally first — a reservation may have a half-finished
+object behind it. If the store delete fails, the **row is kept** so the next sweep
+retries rather than losing the record.
+
+Default cutoff is 24 hours, comfortably beyond any upload URL's lifetime.
+
+> **Two clocks.** `created_at` defaults to PostgreSQL's `now()`, while the default
+> cutoff uses the service's injected clock. A day of slack makes any realistic skew
+> between an application server and the database irrelevant — pass `olderThan` if
+> you need it exact.
+
+---
+
+## `sanitizeFilename(filename)`
+
+The filename never becomes part of a key, so this is **not** a traversal defence.
+It exists because the value is displayed and put in a `Content-Disposition` header:
+
+- keeps only the leaf, so `C:\Users\me\report.pdf` becomes `report.pdf`
+- strips control characters, which can break a header
+- strips leading dots
+- caps at 255 characters, so it cannot break every UI that renders it
+- throws when nothing usable remains
+
+---
+
+## Lifecycle
+
+| Deleted | Effect |
+| --- | --- |
+| Workspace | file rows cascade away |
+| Uploading user | `uploaded_by_user_id` set null; the file survives |
+
+The file outliving its uploader is deliberate — a departing employee's uploads
+belong to the workspace, not to them.
+
+Note that deleting a *row* directly (a cascade, or your own SQL) does **not**
+remove the object. Delete through `files.delete` where you can; for a cascade,
+reconcile with `purgeAbandoned`-style sweeping of your own.
+
+---
+
+## Testing
+
+```ts
+const provider = createMemoryStorageProvider();
+const files = createFilesService({
+  db,
+  storage: createStorageService({ provider }),
+  maxBytes: 1024,
+  now: () => fixedClock,
+});
+
+const { file } = await files.createUpload(context, { filename: "a.csv" });
+await provider.put({ key: file.storageKey, body: "a,b,c" });   // stand in for the browser
+expect((await files.confirmUpload(context, file.id)).sizeBytes).toBe(5);
+```

package/docs/jobs.md

@@ -0,0 +1,288 @@
+# Background jobs
+
+```ts
+import { jobs, task, configureJobs } from "@digimuza/saas-core/jobs";
+import type { JobPayload } from "@digimuza/saas-core/jobs";
+```
+
+> Orientation and recipes: [`src/jobs/README.md`](../src/jobs/README.md).
+
+
+Trigger.dev owns durable execution — retries, scheduling, cron, waits, concurrency,
+multi-step workflows and run observability. The core reimplements none of it and
+**stores no run state**: a `job_runs` table would be a second, always-slightly-wrong
+copy of what Trigger.dev already knows.
+
+What the core adds is exactly two things:
+
+1. **Tenant attribution.** A job outlives the request that queued it, so the
+   workspace travels with it.
+2. **Application events.** `job.started` / `.progress` / `.completed` / `.failed`,
+   so the rest of the system can react.
+
+Everything else is Trigger.dev's, and the SDK is re-exported rather than wrapped,
+so advanced use is never blocked.
+
+---
+
+## Install and configure
+
+`@trigger.dev/sdk` is an **optional peer dependency**. Install it in your
+application — an app defines its tasks against the same SDK instance the core
+triggers through, and two copies would not share task registries.
+
+```bash
+npm install @trigger.dev/sdk
+```
+
+```ts
+import { configureJobs } from "@digimuza/saas-core/jobs";
+
+await configureJobs();   // once at startup
+```
+
+This points the SDK at the Infisical-injected `TRIGGER_SECRET_KEY` and
+`TRIGGER_API_URL`. Without it the SDK reads the environment itself, which works but
+bypasses the validation every other config section gets.
+
+---
+
+## `jobs.trigger(taskId, data, options)`
+
+```ts
+function trigger<TData>(taskId: string, data: TData, options: {
+  workspaceId: string;
+  actorId?: string | null;
+  idempotencyKey?: string | string[];
+  idempotencyKeyTTL?: string;
+  maxAttempts?: number;
+  queue?: string;
+  concurrencyKey?: string;
+  delay?: string | Date;
+  ttl?: string | number;
+  priority?: number;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+}): Promise<{ runId: string; taskId: string }>
+```
+
+```ts
+const handle = await jobs.trigger("resize-image", { assetId }, {
+  workspaceId: context.workspaceId,
+  actorId: user.id,
+  idempotencyKey: requestId,
+  concurrencyKey: context.workspaceId,   // one tenant cannot starve another
+});
+```
+
+Three things happen beyond a plain `tasks.trigger`:
+
+- The payload is wrapped in a `JobPayload` envelope, so your data stays untouched
+  under `data`. A payload with its own `tenant` field keeps working.
+- The run is tagged `workspace:<id>` and `actor:<id>`, so runs are filterable per
+  tenant in the Trigger.dev dashboard. Caller tags are merged and de-duplicated,
+  since Trigger.dev counts them against a per-run limit.
+- Tenancy is mirrored into run **metadata**, which is what makes a production
+  incident searchable back to a tenant.
+
+`workspaceId` and `actorId` are stripped from what reaches Trigger.dev — they are
+core concepts, not SDK options.
+
+Throws `InvalidInputError` for a blank task id or workspace id.
+
+## `jobs.triggerSystem(taskId, data, options?)`
+
+```ts
+function triggerSystem<TData>(taskId: string, data: TData, options?: JobTriggerOptions):
+  Promise<{ runId: string; taskId: string }>
+```
+
+For work that belongs to no tenant — a nightly sweep, a catalogue sync. Sends
+`tenant: null` and no tenant tags.
+
+A separate method rather than accepting a null workspace, so forgetting to
+attribute tenant work is a deliberate choice and not a typo.
+
+---
+
+## Writing a task
+
+```ts
+import { task } from "@digimuza/saas-core/jobs";
+import type { JobPayload } from "@digimuza/saas-core/jobs";
+import { jobs } from "@digimuza/saas-core/jobs";
+import { workspaces } from "@digimuza/saas-core/workspaces";
+
+export const resizeImage = task({
+  id: "resize-image",
+  run: async (payload: JobPayload<{ assetId: string }>, { ctx }) => {
+    const reporter = jobs.reporter(
+      { runId: ctx.run.id, taskId: ctx.task.id },
+      payload.tenant,
+    );
+    await reporter.started();
+
+    // Re-verify. The payload is attribution, not authority.
+    const context = await workspaces.requireContext({
+      userId: payload.tenant.actorId!,
+      workspaceId: payload.tenant.workspaceId,
+    });
+
+    try {
+      await doWork(context, payload.data);
+      await reporter.completed();
+    } catch (error) {
+      await reporter.failed({ error, attempt: ctx.attempt.number });
+      throw error;   // rethrow so Trigger.dev retries
+    }
+  },
+});
+```
+
+### Always re-verify tenancy inside the task
+
+`JobPayload.tenant` is **attribution, not authorisation**. Between queueing and
+running, the workspace may have been deleted or the actor removed from it. Call
+`workspaces.requireContext()` before touching tenant data — it is one indexed query
+and it closes the gap.
+
+For a system job (`tenant: null`) there is no membership to check; resolve whatever
+scope the task needs explicitly.
+
+---
+
+## `jobs.reporter(run, tenant)`
+
+```ts
+function reporter(run: { runId: string; taskId: string }, tenant: JobTenant | null): JobReporter
+
+interface JobReporter {
+  started(): Promise<void>;
+  progress(progress: {
+    percent?: number;      // 0-100
+    message?: string;      // max 500 chars
+    step?: number;
+    totalSteps?: number;
+  }): Promise<void>;
+  completed(result?: { durationMs?: number }): Promise<void>;
+  failed(input: { error: unknown; attempt?: number }): Promise<void>;
+}
+```
+
+Emits `job.*` application events so the application can react and a browser can
+watch progress. These are **not** a second source of truth — Trigger.dev already
+tracks run state, and losing one of these events does not lose the run.
+
+Deduplication is chosen per method, deliberately:
+
+| Method | Key | Why |
+| --- | --- | --- |
+| `started` | run id | A Trigger.dev retry re-executes the task body; the run has not restarted. |
+| `completed` | run id | One completion per run. |
+| `failed` | run id + attempt | Each failed attempt is a distinct fact; a run failing twice should say so twice. |
+| `progress` | none | Every tick is news. |
+
+`completed()` computes `durationMs` from reporter construction if you do not supply
+one.
+
+`failed()` reduces any throwable to a bounded string via `describeJobError`, capped
+at 2000 characters so the event schema accepts it. **Never put a secret in a task
+error** — the message is persisted and readable.
+
+### Throttle progress
+
+Each `progress()` call writes a row. A tight loop would turn the events table into
+a firehose. Report on meaningful steps, or rate-limit to a few per second.
+
+### Without an event publisher
+
+`createJobsService({ backend })` — no `events` — returns a reporter whose methods do
+nothing, so a task can call it unconditionally without branching.
+
+---
+
+## The Trigger.dev SDK, re-exported
+
+```ts
+import {
+  task, tasks, schemaTask, schedules, wait, retry, queue, queues,
+  batch, runs, tags, metadata, logger, timeout, usage, idempotencyKeys,
+  configureTriggerClient,
+} from "@digimuza/saas-core/jobs";
+```
+
+Deliberately unwrapped. Wrapping `task`, `schedules` or `wait` would mean
+re-documenting and re-typing a mature API for no gain, and would lag behind it.
+
+So scheduled jobs, cron, waits, multi-step workflows and concurrency controls are
+all used exactly as Trigger.dev documents them:
+
+```ts
+import { schedules } from "@digimuza/saas-core/jobs";
+
+export const nightly = schedules.task({
+  id: "nightly-sweep",
+  cron: "0 3 * * *",
+  run: async () => { /* ... */ },
+});
+```
+
+Importing this module does not require credentials — there is a test asserting the
+entry point loads with none set.
+
+---
+
+## Subscribing to job events
+
+```ts
+import { events } from "@digimuza/saas-core/events";
+
+events.on("job.progress", (event) => {
+  event.data.percent;   // narrowed
+});
+```
+
+The intended architecture, end to end:
+
+```
+Trigger.dev task → reporter → events table → realtime → RxJS → browser UI
+```
+
+Realtime is Phase 8 and RxJS Phase 9; today the events are persisted and
+in-process subscribers fire.
+
+---
+
+## Custom construction
+
+```ts
+import { createJobsService, createTriggerDevBackend } from "@digimuza/saas-core/jobs";
+
+const jobs = createJobsService({
+  backend: createTriggerDevBackend(),
+  events,
+});
+```
+
+`JobBackend` is a one-method interface, so tests pass a recorder instead of needing
+a Trigger.dev account:
+
+```ts
+const calls: unknown[] = [];
+const jobs = createJobsService({
+  backend: {
+    trigger(taskId, payload, options) {
+      calls.push({ taskId, payload, options });
+      return Promise.resolve({ id: "run_1" });
+    },
+  },
+});
+```
+
+---
+
+## What is not here
+
+No Redis. PostgreSQL and Trigger.dev cover durable state and durable execution
+between them; adding Redis for background jobs would be operational complexity with
+nothing to show for it.