@homeflare/alchemy 0.24.0 → 0.25.1

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

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

@@ -0,0 +1,37 @@
+/**
+ * Generated Paperless-ngx REST API (OpenAPI 3.0.3) request/response types 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
+ *
+ * 8 of Paperless-ngx REST API (OpenAPI 3.0.3)'s 100 write endpoints are used by this family; this file covers only /api/tags/.
+ *
+ * ⛔ `set_permissions` (writeOnly) is not modelled in this slice — no property here writes it.
+ */
+export interface PaperlessTagRequest {
+  name: string;
+  color?: string;
+  match?: string;
+  matching_algorithm?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  is_insensitive?: boolean;
+  is_inbox_tag?: boolean;
+  owner?: number | null;
+  parent?: number | null;
+}
+
+export interface PaperlessTag {
+  readonly id: number;
+  readonly slug: string;
+  name: string;
+  color?: string;
+  readonly text_color: string;
+  match?: string;
+  matching_algorithm?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  is_insensitive?: boolean;
+  is_inbox_tag?: boolean;
+  readonly document_count: number;
+  owner?: number | null;
+  readonly user_can_change: boolean;
+  parent?: number | null;
+  readonly children: number[];
+}

package/src/paperless/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Paperless-ngx taxonomy providers for Alchemy: Tag, DocumentType, StoragePath, CustomField.
+ *
+ * ⛔ THIS BARREL IS SMALLER THAN THE DIRECTORY ON PURPOSE — see `../netbox/index.ts`'s own
+ *   header. `matching.ts`'s internals and the raw generated modules are not re-exported; a
+ *   consumer wanting the same guard a Resource uses gets it through `constraintsFor`/
+ *   `bodyViolations`, not by importing `generated/` directly.
+ */
+export {
+  PaperlessCredentials,
+  type PaperlessCredentialValue,
+  PaperlessCredentialsError,
+  environmentLayer as paperlessEnvironmentLayer,
+} from './credentials.ts';
+export {
+  PaperlessNotFound,
+  PaperlessUnauthorized,
+  PaperlessValidation,
+  PaperlessUnavailable,
+  type PaperlessError,
+} from './errors.ts';
+export {
+  PAPERLESS_CONSTRAINTS,
+  bodyViolations,
+  constraintsFor,
+  guardBody,
+} from './constraint-guard.ts';
+export {
+  type EndpointConstraints,
+  type EndpointKey,
+  type ParamConstraint,
+  type PaperlessBody,
+  refusal,
+  violations,
+} from './constraints.ts';
+export { PAPERLESS_CONSTRAINTS_DIGEST } from './generated/constraints/index.ts';
+export { Tag, TagProvider, type TagAttributes, type TagProps } from './tag.ts';
+export {
+  DocumentType,
+  DocumentTypeProvider,
+  type DocumentTypeAttributes,
+  type DocumentTypeProps,
+} from './document-type.ts';
+export {
+  StoragePath,
+  StoragePathProvider,
+  type StoragePathAttributes,
+  type StoragePathProps,
+} from './storage-path.ts';
+export {
+  CustomField,
+  CustomFieldProvider,
+  type CustomFieldAttributes,
+  type CustomFieldProps,
+} from './custom-field.ts';
+export { paperlessProviders } from './providers.ts';