@homeflare/alchemy 0.23.0 → 0.25.0

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

package/src/paperless/fake-paperless.ts

@@ -0,0 +1,156 @@
+/**
+ * A fake Paperless-ngx for the tests beside it — `Bun.serve` on an ephemeral 127.0.0.1 port, the
+ * same shape `../openbao/fake-bao.ts` and `../caddy/fake-caddy.ts` use.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file. It stores rows in memory for exactly the four
+ *   taxonomy collections and answers `name__iexact` the way Django does — case-insensitive,
+ *   never collapsing two differently-cased rows into one.
+ */
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type { PaperlessRequirements } from './client.ts';
+import { type PaperlessCredentialsError, environmentLayer } from './credentials.ts';
+import type { PaperlessError } from './errors.ts';
+
+export const FAKE_TOKEN = 'fake-token-not-real';
+
+export interface Seen {
+  readonly method: string;
+  readonly path: string;
+  readonly headers: Headers;
+  readonly body: string;
+}
+
+export type Row = Record<string, unknown> & { id: number };
+
+const COLLECTIONS = ['tags', 'document_types', 'storage_paths', 'custom_fields'] as const;
+
+export interface FakePaperless {
+  readonly url: string;
+  readonly seen: Seen[];
+  readonly rows: (collection: (typeof COLLECTIONS)[number]) => readonly Row[];
+  /** `undefined` to answer normally; a status to force it once per subsequent call. */
+  forceStatus: number | undefined;
+  stop(): void;
+}
+
+const nextId = (store: Row[]): number =>
+  store.length === 0 ? 1 : Math.max(...store.map((r) => r.id)) + 1;
+
+export const fakePaperless = (): FakePaperless => {
+  const seen: Seen[] = [];
+  const store = new Map<(typeof COLLECTIONS)[number], Row[]>(COLLECTIONS.map((c) => [c, []]));
+  let forced: number | undefined;
+
+  const fetch = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const body = await request.text();
+    seen.push({
+      body,
+      headers: request.headers,
+      method: request.method,
+      path: `${url.pathname}${url.search}`,
+    });
+
+    const token = request.headers.get('Authorization');
+    if (token !== `Token ${FAKE_TOKEN}`) return json(401, { detail: 'Invalid token.' });
+    if (forced !== undefined) {
+      const status = forced;
+      forced = undefined;
+      return json(status, { detail: 'injected for the test' });
+    }
+
+    const segments = url.pathname.split('/').filter((s) => s !== '');
+    // ['api', collection, (id)?]
+    const collection = segments[1] as (typeof COLLECTIONS)[number] | undefined;
+    if (collection === undefined || !COLLECTIONS.includes(collection))
+      return json(404, { detail: 'Not found.' });
+    const rows = store.get(collection) as Row[];
+    const id = segments[2] === undefined ? undefined : Number(segments[2]);
+
+    if (request.method === 'GET' && id === undefined) {
+      const filter = url.searchParams.get('name__iexact');
+      const matched =
+        filter === null
+          ? rows
+          : rows.filter((r) => String(r['name']).toLowerCase() === filter.toLowerCase());
+      return json(200, { count: matched.length, next: null, previous: null, results: matched });
+    }
+    if (request.method === 'POST' && id === undefined) {
+      const row: Row = { id: nextId(rows), ...(JSON.parse(body) as Record<string, unknown>) };
+      rows.push(row);
+      return json(201, row);
+    }
+    const found = id === undefined ? undefined : rows.find((r) => r.id === id);
+    if (found === undefined) return json(404, { detail: 'Not found.' });
+    if (request.method === 'GET') return json(200, found);
+    if (request.method === 'PATCH') {
+      Object.assign(found, JSON.parse(body) as Record<string, unknown>);
+      return json(200, found);
+    }
+    if (request.method === 'DELETE') {
+      store.set(
+        collection,
+        rows.filter((r) => r.id !== id),
+      );
+      return new Response(null, { status: 204 });
+    }
+    return json(405, { detail: 'method not allowed' });
+  };
+
+  const server = Bun.serve({ fetch, hostname: '127.0.0.1', port: 0 });
+  return {
+    get forceStatus() {
+      return forced;
+    },
+    set forceStatus(value: number | undefined) {
+      forced = value;
+    },
+    rows: (collection) => store.get(collection) ?? [],
+    seen,
+    stop: () => void server.stop(true),
+    url: server.url.origin,
+  };
+};
+
+const json = (status: number, body: unknown): Response =>
+  new Response(status === 204 ? null : JSON.stringify(body), {
+    headers: { 'content-type': 'application/json' },
+    status,
+  });
+
+/** Run `body` against a fresh fake, `PAPERLESS_URL`/`PAPERLESS_TOKEN` set only for its duration. */
+export const withFake = async (body: (fake: FakePaperless) => Promise<void>): Promise<void> => {
+  const fake = fakePaperless();
+  const savedUrl = process.env['PAPERLESS_URL'];
+  const savedToken = process.env['PAPERLESS_TOKEN'];
+  process.env['PAPERLESS_URL'] = fake.url;
+  process.env['PAPERLESS_TOKEN'] = FAKE_TOKEN;
+  try {
+    await body(fake);
+  } finally {
+    fake.stop();
+    if (savedUrl === undefined) delete process.env['PAPERLESS_URL'];
+    else process.env['PAPERLESS_URL'] = savedUrl;
+    if (savedToken === undefined) delete process.env['PAPERLESS_TOKEN'];
+    else process.env['PAPERLESS_TOKEN'] = savedToken;
+  }
+};
+
+/** Run an effect through the real `FetchHttpClient` and the real environment credentials layer. */
+export const run = <A>(
+  effect: Effect.Effect<A, PaperlessError | PaperlessCredentialsError, PaperlessRequirements>,
+) =>
+  Effect.runPromise(
+    effect.pipe(Effect.provide(FetchHttpClient.layer), Effect.provide(environmentLayer)),
+  );
+
+export const runFailure = <A>(
+  effect: Effect.Effect<A, PaperlessError | PaperlessCredentialsError, PaperlessRequirements>,
+) =>
+  Effect.runPromise(
+    Effect.flip(effect).pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(environmentLayer),
+    ),
+  );

package/src/paperless/generated/constraints/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Every generated Paperless constraint table, merged — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/paperless.ts
+ *
+ * ⚠️ EVERY KEY IS PREFIXED `paperless:`, so one estate running several vendors' readers cannot
+ *   collide on an unprefixed `POST /api/…`.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+import { PAPERLESS_CUSTOM_FIELDS_CONSTRAINTS } from './paperless-custom_fields.ts';
+import { PAPERLESS_DOCUMENT_TYPES_CONSTRAINTS } from './paperless-document_types.ts';
+import { PAPERLESS_STORAGE_PATHS_CONSTRAINTS } from './paperless-storage_paths.ts';
+import { PAPERLESS_TAGS_CONSTRAINTS } from './paperless-tags.ts';
+
+export const PAPERLESS_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  ...PAPERLESS_CUSTOM_FIELDS_CONSTRAINTS,
+  ...PAPERLESS_DOCUMENT_TYPES_CONSTRAINTS,
+  ...PAPERLESS_STORAGE_PATHS_CONSTRAINTS,
+  ...PAPERLESS_TAGS_CONSTRAINTS,
+};
+
+/** sha256 of the merged table, truncated — a digest of the DATA, not the file text. */
+export const PAPERLESS_CONSTRAINTS_DIGEST = '66e61dce8c099d7d';

package/src/paperless/generated/constraints/paperless-custom_fields.ts

@@ -0,0 +1,29 @@
+/**
+ * Generated Paperless-ngx REST API (OpenAPI 3.0.3) request-body constraints for `/api/custom_fields/` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/paperless.ts
+ * Manifest entry: `paperless-openapi` — Paperless-ngx REST API (OpenAPI 3.0.3) 3.1.1
+ *   sha256 d0fe550d2135e37b, Paperless-ngx web service, loopback
+ *   /api/schema/?format=json
+ *
+ * 8 of this product's 100 POST/PUT/PATCH/DELETE endpoints are tabled across all
+ * areas: the ones this package writes to, named in its own source. Every other vendor write
+ * endpoint is UNTABLED and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it could NOT be carried into a JavaScript
+ *   RegExp faithfully — Django/DRF's `\w` is Unicode and JavaScript's is ASCII
+ *   (codegen/py-pattern.ts). It is recorded and NOT enforced.
+ * ⚠️ `data_type` on a custom field is CREATE-ONLY: enforced here as a value rule, never as a
+ *   reason to allow a PATCH — the refusal on change lives in the provider (custom-field.ts).
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const PAPERLESS_CUSTOM_FIELDS_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "paperless:PATCH /api/custom_fields/{id}/": {
+    "name": {"maxLength":128,"minLength":1,"type":"string"},
+  },
+  "paperless:POST /api/custom_fields/": {
+    "data_type": {"required":true},
+    "name": {"maxLength":128,"minLength":1,"required":true,"type":"string"},
+  },
+};

package/src/paperless/generated/constraints/paperless-document_types.ts

@@ -0,0 +1,32 @@
+/**
+ * Generated Paperless-ngx REST API (OpenAPI 3.0.3) request-body constraints for `/api/document_types/` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/paperless.ts
+ * Manifest entry: `paperless-openapi` — Paperless-ngx REST API (OpenAPI 3.0.3) 3.1.1
+ *   sha256 d0fe550d2135e37b, Paperless-ngx web service, loopback
+ *   /api/schema/?format=json
+ *
+ * 8 of this product's 100 POST/PUT/PATCH/DELETE endpoints are tabled across all
+ * areas: the ones this package writes to, named in its own source. Every other vendor write
+ * endpoint is UNTABLED and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it could NOT be carried into a JavaScript
+ *   RegExp faithfully — Django/DRF's `\w` is Unicode and JavaScript's is ASCII
+ *   (codegen/py-pattern.ts). It is recorded and NOT enforced.
+ * ⚠️ `data_type` on a custom field is CREATE-ONLY: enforced here as a value rule, never as a
+ *   reason to allow a PATCH — the refusal on change lives in the provider (custom-field.ts).
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const PAPERLESS_DOCUMENT_TYPES_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "paperless:PATCH /api/document_types/{id}/": {
+    "match": {"maxLength":256,"type":"string"},
+    "matching_algorithm": {"enum":[0,1,2,3,4,5,6],"type":"integer"},
+    "name": {"maxLength":128,"minLength":1,"type":"string"},
+  },
+  "paperless:POST /api/document_types/": {
+    "match": {"maxLength":256,"type":"string"},
+    "matching_algorithm": {"enum":[0,1,2,3,4,5,6],"type":"integer"},
+    "name": {"maxLength":128,"minLength":1,"required":true,"type":"string"},
+  },
+};

package/src/paperless/generated/constraints/paperless-storage_paths.ts

@@ -0,0 +1,34 @@
+/**
+ * Generated Paperless-ngx REST API (OpenAPI 3.0.3) request-body constraints for `/api/storage_paths/` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/paperless.ts
+ * Manifest entry: `paperless-openapi` — Paperless-ngx REST API (OpenAPI 3.0.3) 3.1.1
+ *   sha256 d0fe550d2135e37b, Paperless-ngx web service, loopback
+ *   /api/schema/?format=json
+ *
+ * 8 of this product's 100 POST/PUT/PATCH/DELETE endpoints are tabled across all
+ * areas: the ones this package writes to, named in its own source. Every other vendor write
+ * endpoint is UNTABLED and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it could NOT be carried into a JavaScript
+ *   RegExp faithfully — Django/DRF's `\w` is Unicode and JavaScript's is ASCII
+ *   (codegen/py-pattern.ts). It is recorded and NOT enforced.
+ * ⚠️ `data_type` on a custom field is CREATE-ONLY: enforced here as a value rule, never as a
+ *   reason to allow a PATCH — the refusal on change lives in the provider (custom-field.ts).
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const PAPERLESS_STORAGE_PATHS_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "paperless:PATCH /api/storage_paths/{id}/": {
+    "match": {"maxLength":256,"type":"string"},
+    "matching_algorithm": {"enum":[0,1,2,3,4,5,6],"type":"integer"},
+    "name": {"maxLength":128,"minLength":1,"type":"string"},
+    "path": {"minLength":1,"type":"string"},
+  },
+  "paperless:POST /api/storage_paths/": {
+    "match": {"maxLength":256,"type":"string"},
+    "matching_algorithm": {"enum":[0,1,2,3,4,5,6],"type":"integer"},
+    "name": {"maxLength":128,"minLength":1,"required":true,"type":"string"},
+    "path": {"minLength":1,"required":true,"type":"string"},
+  },
+};

package/src/paperless/generated/constraints/paperless-tags.ts

@@ -0,0 +1,34 @@
+/**
+ * Generated Paperless-ngx REST API (OpenAPI 3.0.3) request-body constraints for `/api/tags/` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/paperless.ts
+ * Manifest entry: `paperless-openapi` — Paperless-ngx REST API (OpenAPI 3.0.3) 3.1.1
+ *   sha256 d0fe550d2135e37b, Paperless-ngx web service, loopback
+ *   /api/schema/?format=json
+ *
+ * 8 of this product's 100 POST/PUT/PATCH/DELETE endpoints are tabled across all
+ * areas: the ones this package writes to, named in its own source. Every other vendor write
+ * endpoint is UNTABLED and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it could NOT be carried into a JavaScript
+ *   RegExp faithfully — Django/DRF's `\w` is Unicode and JavaScript's is ASCII
+ *   (codegen/py-pattern.ts). It is recorded and NOT enforced.
+ * ⚠️ `data_type` on a custom field is CREATE-ONLY: enforced here as a value rule, never as a
+ *   reason to allow a PATCH — the refusal on change lives in the provider (custom-field.ts).
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const PAPERLESS_TAGS_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "paperless:PATCH /api/tags/{id}/": {
+    "color": {"maxLength":7,"minLength":1,"type":"string"},
+    "match": {"maxLength":256,"type":"string"},
+    "matching_algorithm": {"enum":[0,1,2,3,4,5,6],"type":"integer"},
+    "name": {"maxLength":128,"minLength":1,"type":"string"},
+  },
+  "paperless:POST /api/tags/": {
+    "color": {"maxLength":7,"minLength":1,"type":"string"},
+    "match": {"maxLength":256,"type":"string"},
+    "matching_algorithm": {"enum":[0,1,2,3,4,5,6],"type":"integer"},
+    "name": {"maxLength":128,"minLength":1,"required":true,"type":"string"},
+  },
+};

package/src/paperless/generated/types/custom-fields.ts

@@ -0,0 +1,23 @@
+/**
+ * Generated Paperless-ngx REST API (OpenAPI 3.0.3) request/response types for `/api/custom_fields/` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/paperless.ts
+ * Manifest entry: `paperless-openapi` — Paperless-ngx REST API (OpenAPI 3.0.3) 3.1.1, sha256 d0fe550d2135e37b
+ *
+ * 8 of Paperless-ngx REST API (OpenAPI 3.0.3)'s 100 write endpoints are used by this family; this file covers only /api/custom_fields/.
+ *
+ * ⛔ `set_permissions` (writeOnly) is not modelled in this slice — no property here writes it.
+ */
+export interface PaperlessCustomFieldRequest {
+  name: string;
+  data_type: "string" | "url" | "date" | "boolean" | "integer" | "float" | "monetary" | "documentlink" | "select" | "longtext";
+  extra_data?: unknown | null;
+}
+
+export interface PaperlessCustomField {
+  readonly id: number;
+  name: string;
+  data_type: "string" | "url" | "date" | "boolean" | "integer" | "float" | "monetary" | "documentlink" | "select" | "longtext";
+  extra_data?: unknown | null;
+  readonly document_count: number;
+}

package/src/paperless/generated/types/document-types.ts

@@ -0,0 +1,30 @@
+/**
+ * Generated Paperless-ngx REST API (OpenAPI 3.0.3) request/response types for `/api/document_types/` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/paperless.ts
+ * Manifest entry: `paperless-openapi` — Paperless-ngx REST API (OpenAPI 3.0.3) 3.1.1, sha256 d0fe550d2135e37b
+ *
+ * 8 of Paperless-ngx REST API (OpenAPI 3.0.3)'s 100 write endpoints are used by this family; this file covers only /api/document_types/.
+ *
+ * ⛔ `set_permissions` (writeOnly) is not modelled in this slice — no property here writes it.
+ */
+export interface PaperlessDocumentTypeRequest {
+  name: string;
+  match?: string;
+  matching_algorithm?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  is_insensitive?: boolean;
+  owner?: number | null;
+}
+
+export interface PaperlessDocumentType {
+  readonly id: number;
+  readonly slug: string;
+  name: string;
+  match?: string;
+  matching_algorithm?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  is_insensitive?: boolean;
+  readonly document_count: number;
+  owner?: number | null;
+  readonly permissions: { view?: { users?: number[]; groups?: number[] }; change?: { users?: number[]; groups?: number[] } };
+  readonly user_can_change: boolean;
+}

package/src/paperless/generated/types/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Every generated Paperless taxonomy type, re-exported — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/paperless.ts
+ */
+export * from './tags.ts';
+export * from './document-types.ts';
+export * from './storage-paths.ts';
+export * from './custom-fields.ts';

package/src/paperless/generated/types/storage-paths.ts

@@ -0,0 +1,31 @@
+/**
+ * Generated Paperless-ngx REST API (OpenAPI 3.0.3) request/response types for `/api/storage_paths/` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/paperless.ts
+ * Manifest entry: `paperless-openapi` — Paperless-ngx REST API (OpenAPI 3.0.3) 3.1.1, sha256 d0fe550d2135e37b
+ *
+ * 8 of Paperless-ngx REST API (OpenAPI 3.0.3)'s 100 write endpoints are used by this family; this file covers only /api/storage_paths/.
+ *
+ * ⛔ `set_permissions` (writeOnly) is not modelled in this slice — no property here writes it.
+ */
+export interface PaperlessStoragePathRequest {
+  name: string;
+  path: string;
+  match?: string;
+  matching_algorithm?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  is_insensitive?: boolean;
+  owner?: number | null;
+}
+
+export interface PaperlessStoragePath {
+  readonly id: number;
+  readonly slug: string;
+  name: string;
+  path: string;
+  match?: string;
+  matching_algorithm?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  is_insensitive?: boolean;
+  readonly document_count: number;
+  owner?: number | null;
+  readonly user_can_change: boolean;
+}