@homeflare/alchemy 0.24.0 → 0.25.1

package/src/paperless/constraints.test.ts

@@ -0,0 +1,74 @@
+/**
+ * The generated Paperless constraint tables, exercised at the boundary a plan actually checks:
+ * `bodyViolations` against the real generated data, not a literal table constructed by hand.
+ *
+ * ⛔ THESE TESTS FAIL WITHOUT THE UNIT. Before `codegen/paperless.ts` and `generated/constraints/`
+ *   existed, `constraintsFor('paperless:POST /api/tags/')` threw "no vendor constraint table" —
+ *   there was nothing to import.
+ */
+import { describe, expect, test } from 'bun:test';
+import { bodyViolations, constraintsFor } from './constraint-guard.ts';
+
+const CREATE = 'paperless:POST /api/tags/';
+
+describe('a 129-character name is refused, a 128-character one is not', () => {
+  test('129 plain characters', () => {
+    const found = bodyViolations(CREATE, { name: 'a'.repeat(129) }, true);
+    expect(found.some((f) => f.includes('name'))).toBe(true);
+  });
+
+  /** ⚠️ Counts CHARACTERS, not UTF-16 units — an astral emoji is one character to Django. */
+  test('128 astral characters (each a surrogate pair) passes the length check', () => {
+    const found = bodyViolations(CREATE, { name: '😀'.repeat(128) }, true);
+    expect(found.some((f) => f.includes('name'))).toBe(false);
+  });
+
+  test('129 astral characters is refused', () => {
+    const found = bodyViolations(CREATE, { name: '😀'.repeat(129) }, true);
+    expect(found.some((f) => f.includes('name'))).toBe(true);
+  });
+});
+
+describe('a 256-plus character match is refused', () => {
+  test('256 characters passes, 257 does not', () => {
+    expect(bodyViolations(CREATE, { match: 'a'.repeat(256), name: 'x' }, false)).toEqual([]);
+    const found = bodyViolations(CREATE, { match: 'a'.repeat(257), name: 'x' }, false);
+    expect(found.some((f) => f.includes('match'))).toBe(true);
+  });
+});
+
+describe('presence is create-only', () => {
+  test('a missing required name is refused on create', () => {
+    expect(bodyViolations(CREATE, {}, true).some((f) => f.includes('required'))).toBe(true);
+  });
+
+  /** ⚠️ An update is PATCH, deliberately partial — presence must not fire without `presence: true`. */
+  test('the same missing name is not refused on update', () => {
+    expect(bodyViolations(CREATE, {}, false)).toEqual([]);
+  });
+});
+
+describe('null is a value, not an absence', () => {
+  test('an explicit null owner on a table that carries no owner rule violates nothing', () => {
+    expect(bodyViolations(CREATE, { name: 'x', owner: null }, true)).toEqual([]);
+  });
+});
+
+describe('every generated table is reachable and carries its provenance', () => {
+  test('all four create endpoints resolve to a non-empty table', () => {
+    for (const key of [
+      'paperless:POST /api/tags/',
+      'paperless:POST /api/document_types/',
+      'paperless:POST /api/storage_paths/',
+      'paperless:POST /api/custom_fields/',
+    ]) {
+      expect(Object.keys(constraintsFor(key)).length).toBeGreaterThan(0);
+    }
+  });
+
+  test('an unknown key names the refresh command rather than silently enforcing nothing', () => {
+    expect(() => constraintsFor('paperless:POST /api/never/')).toThrow(
+      /bun codegen\/paperless\.ts/,
+    );
+  });
+});

package/src/paperless/constraints.ts

@@ -0,0 +1,111 @@
+/**
+ * Paperless-ngx's own rules, checked here, before the request is built.
+ *
+ * ★ THE SAME READER SHAPE AS `../netbox/constraints.ts`, AND FOR THE SAME REASON: both vendors
+ *   send a JSON body where a number stays a number and a boolean stays a boolean, so `String(v)`
+ *   at the door would be the exact mangling that incident (codegen/README.md) exists to prevent.
+ *   The table itself is generated by `bun codegen/paperless.ts` from the vendor's own OpenAPI
+ *   document — nothing here is hand-typed.
+ *
+ * ⚠️ WHAT THIS DELIBERATELY DOES NOT ENFORCE: a `format` name (a DRF validator run server-side); a
+ *   pattern the generator could not carry faithfully (codegen/py-pattern.ts), recorded verbatim as
+ *   `patternSource`; the `(name, owner)` uniqueness constraint (models.py) — that is `matching.ts`'s
+ *   job, not a per-field rule; and `CustomField.select_options`, which is not in the schema at all
+ *   (groundTruth: the serializer's own rule is unverified at 3.1.1 and this table cannot state a
+ *   rule the vendor document does not carry).
+ */
+
+export interface ParamConstraint {
+  readonly type?: string;
+  /** From the schema's `required` array. ⚠️ Checked on CREATE only. */
+  readonly required?: boolean;
+  readonly maxLength?: number;
+  readonly minLength?: number;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  /** ⚠️ `(string | number)[]` — `matching_algorithm`'s enum is numeric (`DataTypeEnum`'s is not). */
+  readonly enum?: readonly (string | number)[];
+  readonly pattern?: string;
+  readonly patternSource?: string;
+  readonly format?: string;
+  readonly default?: string;
+}
+
+export type EndpointConstraints = Readonly<Record<string, ParamConstraint>>;
+
+/** `paperless:POST /api/tags/` — exactly how the generated tables key an endpoint. */
+export type EndpointKey = string;
+
+export type PaperlessBody = Record<string, unknown>;
+
+export interface ViolationOptions {
+  /** ⛔ CREATE ONLY. A PATCH is deliberately partial, so presence there refuses every ordinary edit. */
+  readonly presence?: boolean;
+}
+
+/** ⚠️ `[...value].length`, NOT `value.length` — Django counts characters, JavaScript UTF-16 units. */
+const lengthOf = (value: string): number => [...value].length;
+
+const checkString = (name: string, value: string, rule: ParamConstraint): string[] => {
+  const out: string[] = [];
+  if (rule.maxLength !== undefined && lengthOf(value) > rule.maxLength) {
+    out.push(`${name}: at most ${String(rule.maxLength)} characters`);
+  }
+  if (rule.minLength !== undefined && lengthOf(value) < rule.minLength) {
+    out.push(`${name}: at least ${String(rule.minLength)} characters`);
+  }
+  if (rule.enum !== undefined && !rule.enum.includes(value)) {
+    out.push(`${name}: must be one of ${rule.enum.join(', ')}`);
+  }
+  if (rule.pattern !== undefined && !new RegExp(rule.pattern).test(value)) {
+    out.push(`${name}: must match ${rule.patternSource ?? rule.pattern}`);
+  }
+  return out;
+};
+
+const checkNumber = (name: string, value: number, rule: ParamConstraint): string[] => {
+  const out: string[] = [];
+  if (!Number.isFinite(value)) return out;
+  if (rule.minimum !== undefined && value < rule.minimum)
+    out.push(`${name}: at least ${String(rule.minimum)}`);
+  if (rule.maximum !== undefined && value > rule.maximum)
+    out.push(`${name}: at most ${String(rule.maximum)}`);
+  return out;
+};
+
+const checkValue = (name: string, value: unknown, rule: ParamConstraint): readonly string[] => {
+  if (typeof value === 'string') return checkString(name, value, rule);
+  if (typeof value === 'number') return checkNumber(name, value, rule);
+  return [];
+};
+
+/**
+ * Every vendor rule this body breaks. Pure — no network, no clock, no environment.
+ *
+ * ⚠️ `null` IS A VALUE, NOT AN ABSENCE — Paperless uses explicit `null` to clear a nullable
+ *   foreign key (`owner`, `parent`), so it must not trip the presence check, and no string/number
+ *   rule applies to it.
+ */
+export const violations = (
+  table: EndpointConstraints,
+  body: PaperlessBody,
+  options: ViolationOptions = {},
+): readonly string[] => {
+  const out: string[] = [];
+  for (const [name, rule] of Object.entries(table)) {
+    if (!Object.hasOwn(body, name)) {
+      if (options.presence === true && rule.required === true) out.push(`${name}: required`);
+      continue;
+    }
+    const value = body[name];
+    for (const item of Array.isArray(value) ? value : [value])
+      out.push(...checkValue(name, item, rule));
+  }
+  return out;
+};
+
+/** The message a plan dies with. */
+export const refusal = (endpoint: EndpointKey, found: readonly string[]): string =>
+  `${endpoint} would be rejected by the vendor:\n  - ${found.join('\n  - ')}\n` +
+  "These are Paperless-ngx's own limits, read from its served OpenAPI document " +
+  '(packages/alchemy/src/paperless/generated/constraints). Fix the declaration.';

package/src/paperless/credentials.ts

@@ -0,0 +1,69 @@
+/**
+ * Where the Paperless URL and token come from — S24's shape (alchemy-provider-standard): a lazy
+ * `Context.Service` whose VALUE is itself an `Effect`, resolved inside each operation with
+ * `yield* yield* PaperlessCredentials`. Resolving twice, not once at layer build, is what keeps a
+ * token out of any state the engine might persist and lets a consumer swap the source (an env var
+ * today, an OpenBao mint tomorrow) without touching a resource file.
+ *
+ * ⛔ NO DEFAULT HOST, AND NO DEFAULT TOKEN. A published package that fell back to a loopback
+ *   address would let a consumer who forgot the variable watch every call fail against a machine
+ *   that is not theirs, instead of being told which variable is missing.
+ * ⛔ THE TOKEN IS NEVER A PROP, NEVER AN ATTRIBUTE. Alchemy persists attributes unencrypted
+ *   (S25); nothing this family returns from `read`/`reconcile` may carry it.
+ */
+import * as Context from 'effect/Context';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+export class PaperlessCredentialsError extends Data.TaggedError('PaperlessCredentialsError')<{
+  readonly message: string;
+}> {}
+
+export interface PaperlessCredentialValue {
+  /** Trailing slash stripped, e.g. `https://paperless.example.com`. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * ★ `readEnvironment` NAMES EVERY VARIABLE IT CONSUMES (S24) — `PAPERLESS_URL`, `PAPERLESS_TOKEN`
+ *   — so a consumer's `alchemy provider check-env` (or an equivalent preflight) can list them.
+ */
+const readEnvironment: Effect.Effect<PaperlessCredentialValue, PaperlessCredentialsError> =
+  Effect.suspend(() => {
+    const url = process.env['PAPERLESS_URL'];
+    const token = process.env['PAPERLESS_TOKEN'];
+    if (url === undefined || url.trim() === '') {
+      return Effect.fail(
+        new PaperlessCredentialsError({
+          message: 'PAPERLESS_URL is not set. Point it at your Paperless-ngx instance.',
+        }),
+      );
+    }
+    if (token === undefined || token.trim() === '') {
+      return Effect.fail(
+        new PaperlessCredentialsError({
+          message:
+            'PAPERLESS_TOKEN is not set. Mint a scoped token and export it — never store it in Alchemy props.',
+        }),
+      );
+    }
+    return Effect.succeed({ token: token.trim(), url: url.trim().replace(/\/$/, '') });
+  });
+
+/**
+ * The lazy service. ⚠️ `Layer.succeed` registers the EFFECT, not its result — `readEnvironment`
+ *   runs once per `yield* yield*`, so a call after the variables are exported sees them even if
+ *   the layer itself was built before that (true in `fake-paperless.test.ts`, which sets the env
+ *   vars right before each call).
+ */
+export class PaperlessCredentials extends Context.Service<
+  PaperlessCredentials,
+  Effect.Effect<PaperlessCredentialValue, PaperlessCredentialsError>
+>()('PaperlessCredentials') {}
+
+export const environmentLayer: Layer.Layer<PaperlessCredentials> = Layer.succeed(
+  PaperlessCredentials,
+  readEnvironment,
+);

package/src/paperless/custom-field.test.ts

@@ -0,0 +1,74 @@
+/**
+ * `Paperless.CustomField.dataType` is create-only: a change is refused at plan time, never
+ * silently PATCHed and never routed to a replace. See custom-field.ts's header for why — a
+ * replace would delete the field's value on every document.
+ *
+ * ⛔ THESE TESTS FAIL WITHOUT THE UNIT. `custom-field.ts` did not exist before this change.
+ */
+import { describe, expect, test } from 'bun:test';
+import { customFieldHandlers, dataTypeImmutable } from './custom-field.ts';
+import { run, withFake } from './fake-paperless.ts';
+
+describe('dataTypeImmutable, the pure rule', () => {
+  test('no refusal when the live value is unchanged', () => {
+    expect(
+      dataTypeImmutable({ data_type: 'string', id: 1 }, { dataType: 'string', name: 'x' }),
+    ).toBeUndefined();
+  });
+
+  test('a refusal when the live value differs, naming both values', () => {
+    const message = dataTypeImmutable(
+      { data_type: 'select', id: 1 },
+      { dataType: 'string', name: 'Status' },
+    );
+    expect(message).toMatch(/data_type is create-only/);
+    expect(message).toContain('live: select');
+    expect(message).toContain('declared: string');
+  });
+});
+
+describe('the live lifecycle refuses a data_type change', () => {
+  test('reconcile dies rather than PATCHing a changed data_type', async () => {
+    await withFake(async (fake) => {
+      await run(customFieldHandlers.reconcile({ news: { dataType: 'select', name: 'Status' } }));
+      const before = fake.seen.filter((s) => s.method !== 'GET').length;
+
+      await expect(
+        run(customFieldHandlers.reconcile({ news: { dataType: 'string', name: 'Status' } })),
+      ).rejects.toThrow(/data_type is create-only/);
+
+      // ⛔ NOTHING WAS WRITTEN — the refusal fires before the PATCH, not after a failed one.
+      expect(fake.seen.filter((s) => s.method !== 'GET').length).toBe(before);
+    });
+  });
+
+  test('a create followed by a declaration of the SAME data_type is a normal no-drift reconcile', async () => {
+    await withFake(async () => {
+      await run(customFieldHandlers.reconcile({ news: { dataType: 'select', name: 'Status' } }));
+      const after = await run(
+        customFieldHandlers.reconcile({ news: { dataType: 'select', name: 'Status' } }),
+      );
+      expect(after).toMatchObject({ dataType: 'select', name: 'Status' });
+    });
+  });
+
+  test('extraData still updates through a normal PATCH', async () => {
+    await withFake(async (fake) => {
+      await run(
+        customFieldHandlers.reconcile({
+          news: { dataType: 'select', extraData: { select_options: ['a'] }, name: 'Status' },
+        }),
+      );
+      await run(
+        customFieldHandlers.reconcile({
+          news: { dataType: 'select', extraData: { select_options: ['a', 'b'] }, name: 'Status' },
+        }),
+      );
+      const patch = fake.seen.find((s) => s.method === 'PATCH');
+      expect(patch).toBeDefined();
+      expect(JSON.parse(patch?.body ?? '{}')).toEqual({
+        extra_data: { select_options: ['a', 'b'] },
+      });
+    });
+  });
+});

package/src/paperless/custom-field.ts

@@ -0,0 +1,95 @@
+/**
+ * `Paperless.CustomField` — a Paperless-ngx custom field, create-or-update and never deleted.
+ *
+ * ⛔ `dataType` IS CREATE-ONLY, ENFORCED AT PLAN TIME, NEVER A PATCH AND NEVER A REPLACE. A
+ *   replace would delete this id and create a new one — and Paperless deletes the field's VALUE
+ *   on every document when its custom field is deleted. `matching.ts`'s `immutable` hook carries
+ *   this refusal generically; `dataType` is simply never listed in `fields`, so nothing in
+ *   `matching.ts` ever builds a PATCH body that includes it.
+ *
+ * ⛔ NO `owner` FIELD. Unlike `Tag`/`DocumentType`/`StoragePath`, `CustomField` does not extend
+ *   Paperless-ngx's `OwnedObjectSerializer` — its wire body is exactly `{name, data_type,
+ *   extra_data}` (measured against the v3.1.1 schema). `owned: false` stops `matching.ts`
+ *   sending a field the vendor's serializer does not declare.
+ *
+ * ⚠️ `CustomField.select_options` (the vendor's own rule for a `select` field's option list) is
+ *   not in the served schema at all, so it is recorded here and NOT enforced (groundTruth).
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type { PaperlessCustomFieldRequest } from './generated/types/custom-fields.ts';
+import type { PaperlessRow } from './client.ts';
+import { type MatchingRequirements, matchingHandlers } from './matching.ts';
+
+export interface CustomFieldProps {
+  /** ⚠️ maxLength 128 (generated constraint table). The locate key — CustomField's name is globally unique (models.py:1169), with no owner to further scope it. */
+  name: string;
+  /**
+   * ⛔ CREATE-ONLY — see this file's header. `select`'s own option list
+   *   (`select_options`) is not in the vendor schema and is unenforced here.
+   */
+  dataType: PaperlessCustomFieldRequest['data_type'];
+  /** Arbitrary JSON the vendor attaches no schema to (e.g. a `select` field's option list). */
+  extraData?: unknown;
+}
+
+export interface CustomFieldAttributes {
+  id: number;
+  name: string;
+  dataType: string;
+  extraData: unknown;
+}
+
+export interface CustomField extends Resource<
+  'Paperless.CustomField',
+  CustomFieldProps,
+  CustomFieldAttributes,
+  never,
+  MatchingRequirements
+> {}
+
+export const CustomField = Resource<CustomField>('Paperless.CustomField', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/**
+ * ⛔ EXTRACTED SO IT CAN BE TESTED WITHOUT A SERVER (custom-field.test.ts) — the same reason
+ *   `../netbox/prefix-form.ts` pulls its body/matches functions out of `prefix.ts`.
+ */
+export const dataTypeImmutable = (
+  live: PaperlessRow,
+  props: CustomFieldProps,
+): string | undefined =>
+  typeof live['data_type'] === 'string' && live['data_type'] !== props.dataType
+    ? `Paperless.CustomField "${props.name}": data_type is create-only (live: ${live['data_type']}, ` +
+      `declared: ${props.dataType}). Changing it would delete this field's value on every ` +
+      'document. Create a new custom field instead, and retire this one by hand.'
+    : undefined;
+
+/** ⚠️ Exported (not through index.ts) so custom-field.test.ts can drive the real lifecycle. */
+export const customFieldHandlers = matchingHandlers<CustomFieldProps, CustomFieldAttributes>({
+  attributes: (live, props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    return {
+      dataType: typeof live['data_type'] === 'string' ? live['data_type'] : props.dataType,
+      extraData: live['extra_data'],
+      id,
+      name: typeof live['name'] === 'string' ? live['name'] : props.name,
+    };
+  },
+  collection: 'custom_fields',
+  describe: (props) => `custom_fields ${props.name}`,
+  endpoint: {
+    create: 'paperless:POST /api/custom_fields/',
+    update: 'paperless:PATCH /api/custom_fields/{id}/',
+  },
+  createOnly: [{ key: 'data_type', live: (r) => r['data_type'], prop: (p) => p.dataType }],
+  fields: [{ key: 'extra_data', live: (r) => r['extra_data'], prop: (p) => p.extraData }],
+  immutable: dataTypeImmutable,
+  owned: false,
+});
+
+export const CustomFieldProvider = () =>
+  Provider.effect(CustomField, Effect.succeed(CustomField.Provider.of(customFieldHandlers)));

package/src/paperless/document-type.ts

@@ -0,0 +1,74 @@
+/**
+ * `Paperless.DocumentType` — a Paperless-ngx document type, create-or-update and never deleted.
+ * Same shape as `tag.ts` minus `color`/`isInboxTag`/`parent` — see that file's header for why
+ * `matchingAlgorithm`'s type comes off the generated request type rather than being retyped.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type { PaperlessDocumentTypeRequest } from './generated/types/document-types.ts';
+import { type MatchingProps, type MatchingRequirements, matchingHandlers } from './matching.ts';
+
+export interface DocumentTypeProps extends MatchingProps {
+  /** ⚠️ maxLength 128 (generated constraint table). The locate key. */
+  name: string;
+  /** ⚠️ maxLength 256. */
+  match?: string;
+  matchingAlgorithm?: PaperlessDocumentTypeRequest['matching_algorithm'];
+  isInsensitive?: boolean;
+}
+
+export interface DocumentTypeAttributes {
+  id: number;
+  name: string;
+  match: string;
+  matchingAlgorithm: number;
+  isInsensitive: boolean;
+  owner: number | undefined;
+}
+
+export interface DocumentType extends Resource<
+  'Paperless.DocumentType',
+  DocumentTypeProps,
+  DocumentTypeAttributes,
+  never,
+  MatchingRequirements
+> {}
+
+export const DocumentType = Resource<DocumentType>('Paperless.DocumentType', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const handlers = matchingHandlers<DocumentTypeProps, DocumentTypeAttributes>({
+  attributes: (live, props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    return {
+      id,
+      isInsensitive: live['is_insensitive'] === true,
+      match: typeof live['match'] === 'string' ? live['match'] : '',
+      matchingAlgorithm:
+        typeof live['matching_algorithm'] === 'number' ? live['matching_algorithm'] : 0,
+      name: typeof live['name'] === 'string' ? live['name'] : props.name,
+      owner: typeof live['owner'] === 'number' ? live['owner'] : undefined,
+    };
+  },
+  collection: 'document_types',
+  describe: (props) => `document_types ${props.name}`,
+  endpoint: {
+    create: 'paperless:POST /api/document_types/',
+    update: 'paperless:PATCH /api/document_types/{id}/',
+  },
+  fields: [
+    { key: 'match', live: (r) => r['match'], prop: (p) => p.match },
+    {
+      key: 'matching_algorithm',
+      live: (r) => r['matching_algorithm'],
+      prop: (p) => p.matchingAlgorithm,
+    },
+    { key: 'is_insensitive', live: (r) => r['is_insensitive'], prop: (p) => p.isInsensitive },
+  ],
+});
+
+export const DocumentTypeProvider = () =>
+  Provider.effect(DocumentType, Effect.succeed(DocumentType.Provider.of(handlers)));

package/src/paperless/errors.ts

@@ -0,0 +1,62 @@
+/**
+ * Paperless-ngx's HTTP status codes, mapped to tagged errors exactly once — here, and never
+ * again by a status check inside a resource (S21, alchemy-provider-standard).
+ *
+ * ⛔ A SINGLE `PaperlessError` CLASS WITH A `.status` FIELD WOULD WORK, AND IS WHAT `netbox/
+ *   client.ts` DOES. This family does it the S21 way instead: one tag per distinct MEANING, so a
+ *   caller writes `Effect.catchTag('PaperlessNotFound', …)` rather than `if (e.status === 404)`.
+ *   `matching.ts`'s "a 403 is never read as absent" rule is exactly what a shared tag buys —
+ *   `catchTag('PaperlessNotFound', …)` cannot accidentally also catch `PaperlessUnauthorized`.
+ */
+import * as Data from 'effect/Data';
+
+/** No object at that path. The only tag `matching.ts` folds to "absent". */
+export class PaperlessNotFound extends Data.TaggedError('PaperlessNotFound')<{
+  readonly method: string;
+  readonly path: string;
+}> {}
+
+/** 401 (no/bad token) or 403 (token valid, forbidden) — NEVER read as "the object is absent". */
+export class PaperlessUnauthorized extends Data.TaggedError('PaperlessUnauthorized')<{
+  readonly status: 401 | 403;
+  readonly method: string;
+  readonly path: string;
+}> {}
+
+/** 400 — the vendor rejected the body. Carries it, so the message quotes Paperless's own words. */
+export class PaperlessValidation extends Data.TaggedError('PaperlessValidation')<{
+  readonly method: string;
+  readonly path: string;
+  readonly body: string;
+}> {}
+
+/** 5xx, or a status this family's endpoints do not otherwise document. */
+export class PaperlessUnavailable extends Data.TaggedError('PaperlessUnavailable')<{
+  readonly status: number;
+  readonly method: string;
+  readonly path: string;
+  readonly detail: string;
+}> {}
+
+export type PaperlessError =
+  | PaperlessNotFound
+  | PaperlessUnauthorized
+  | PaperlessValidation
+  | PaperlessUnavailable;
+
+/**
+ * The one place a status code is read. ⚠️ Anything outside {400,401,403,404,5xx} — 405, 409, 429
+ *   — is not documented for these four endpoints, so it falls to `PaperlessValidation` rather than
+ *   inventing a fifth tag for a case that was never measured.
+ */
+export const statusToError = (
+  status: number,
+  method: string,
+  path: string,
+  body: string,
+): PaperlessError => {
+  if (status === 404) return new PaperlessNotFound({ method, path });
+  if (status === 401 || status === 403) return new PaperlessUnauthorized({ method, path, status });
+  if (status >= 500) return new PaperlessUnavailable({ detail: body, method, path, status });
+  return new PaperlessValidation({ body, method, path });
+};