@homeflare/alchemy 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -68,6 +68,10 @@
       "types": "./dist/linux/index.d.ts",
       "default": "./dist/linux/index.js"
     },
+    "./paperless": {
+      "types": "./dist/paperless/index.d.ts",
+      "default": "./dist/paperless/index.js"
+    },
     "./release": {
       "types": "./dist/release/index.d.ts",
       "default": "./dist/release/index.js"

package/src/paperless/client.ts

@@ -0,0 +1,88 @@
+/**
+ * One authenticated call to the Paperless-ngx REST API at `/api`.
+ *
+ * ⚠️ `Authorization: Token <value>`, NOT `Bearer`. Paperless-ngx's `securitySchemes.tokenAuth`
+ *   (the v3.1.1 served schema) states the "Token" prefix explicitly — the same DRF
+ *   `TokenAuthentication` NetBox uses (netbox/client.ts), a different vendor, same convention.
+ *
+ * ⛔ `Accept: application/json; version=10` ON EVERY CALL. Paperless-ngx versions its API with
+ *   DRF's `AcceptHeaderVersioning` (`REST_FRAMEWORK.DEFAULT_VERSION = '10'`, measured against the
+ *   v3.1.1 source). Omitting the header still answers — DRF falls back to `DEFAULT_VERSION` — but
+ *   pinning it here means an estate upgrade that moves the default cannot silently change what
+ *   this package receives without a version bump of its own noticing.
+ *
+ * ⚠️ A LIST IS WRAPPED, A DETAIL IS NOT: `{count, next, previous, results: […]}` vs. the bare
+ *   object — the same DRF pagination shape NetBox uses.
+ */
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import { PaperlessCredentials, type PaperlessCredentialsError } from './credentials.ts';
+import { type PaperlessError, PaperlessUnavailable, statusToError } from './errors.ts';
+
+const PATH_PREFIX = '/api';
+const API_VERSION = '10';
+
+export interface PaperlessList<T> {
+  readonly count: number;
+  readonly next: string | null;
+  readonly previous: string | null;
+  readonly results: readonly T[];
+}
+
+export type PaperlessRow = Record<string, unknown>;
+
+/**
+ * ⚠️ `PaperlessCredentials` IS PART OF THIS, NOT JUST `HttpClient`. `paperless()` reads the lazy
+ *   credentials service (`yield* yield* PaperlessCredentials`), so a stack that wires the
+ *   providers without also providing a credentials layer should fail to TYPECHECK, not fail at
+ *   the first call. `providers.ts` supplies `environmentLayer` by default for exactly this.
+ */
+export type PaperlessRequirements = HttpClient.HttpClient | PaperlessCredentials;
+
+/** One JSON call. Returns the parsed body, or `undefined` for an empty response (DELETE). */
+export const paperless = <T>(
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+): Effect.Effect<T, PaperlessError | PaperlessCredentialsError, PaperlessRequirements> =>
+  Effect.gen(function* () {
+    const credentials = yield* yield* PaperlessCredentials;
+    const url = `${credentials.url}${PATH_PREFIX}/${path.replace(/^\//, '')}`;
+    const client = yield* HttpClient.HttpClient;
+    const request = HttpClientRequest.make(method)(url).pipe(
+      HttpClientRequest.setHeaders({
+        Accept: `application/json; version=${API_VERSION}`,
+        Authorization: `Token ${credentials.token}`,
+      }),
+      // ⛔ Content-Type on `bodyText`, not the header map — `bodyText(s)` with no second argument
+      //   sets `text/plain` and overwrites a `Content-Type` set earlier via `setHeaders`, because
+      //   it is piped afterwards (measured against `@homeflare/alchemy/forgejo`, netbox/client.ts).
+      body === undefined
+        ? (self) => self
+        : HttpClientRequest.bodyText(JSON.stringify(body), 'application/json'),
+    );
+    const response = yield* client
+      .execute(request)
+      .pipe(
+        Effect.mapError(
+          (cause) => new PaperlessUnavailable({ detail: String(cause), method, path, status: 0 }),
+        ),
+      );
+    if (response.status < 200 || response.status >= 300) {
+      const detail = yield* response.text.pipe(Effect.orElseSucceed(() => ''));
+      return yield* Effect.fail(statusToError(response.status, method, path, detail.slice(0, 500)));
+    }
+    const text = yield* response.text.pipe(
+      Effect.mapError(
+        () =>
+          new PaperlessUnavailable({
+            detail: 'body read failed',
+            method,
+            path,
+            status: response.status,
+          }),
+      ),
+    );
+    return (text === '' ? undefined : JSON.parse(text)) as T;
+  });

package/src/paperless/constraint-guard.ts

@@ -0,0 +1,50 @@
+/**
+ * The generated tables, looked up by endpoint, and the refusal that stops a plan.
+ *
+ * ⛔ AN UNKNOWN KEY IS A DEFECT, NOT A REASON TO SKIP THE CHECK — the generator resolves every key
+ *   in its source scan against the vendor document, so a key absent here means the tables were
+ *   not regenerated, which the message says. Same posture as `../netbox/constraint-guard.ts`.
+ */
+import * as Effect from 'effect/Effect';
+import {
+  type EndpointConstraints,
+  type EndpointKey,
+  type PaperlessBody,
+  refusal,
+  violations,
+} from './constraints.ts';
+import { PAPERLESS_CONSTRAINTS } from './generated/constraints/index.ts';
+
+export { PAPERLESS_CONSTRAINTS };
+
+export const constraintsFor = (key: EndpointKey): EndpointConstraints => {
+  const table = PAPERLESS_CONSTRAINTS[key];
+  if (table === undefined) {
+    throw new Error(
+      `no vendor constraint table for '${key}'. It is named in this package but not generated: ` +
+        'run `bun codegen/paperless.ts` (see codegen/README.md).',
+    );
+  }
+  return table;
+};
+
+export const bodyViolations = (
+  key: EndpointKey,
+  body: PaperlessBody,
+  presence: boolean,
+): readonly string[] => violations(constraintsFor(key), body, { presence });
+
+/**
+ * ⛔ `Effect.die`, NOT `Effect.fail`. A declaration the vendor would reject is a DEFECT in the
+ *   stack file, not a recoverable condition.
+ */
+export const guardBody = (
+  key: EndpointKey | undefined,
+  body: PaperlessBody,
+  presence: boolean,
+): Effect.Effect<void> =>
+  Effect.suspend(() => {
+    if (key === undefined) return Effect.void;
+    const found = bodyViolations(key, body, presence);
+    return found.length === 0 ? Effect.void : Effect.die(new Error(refusal(key, found)));
+  });

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)));