@homeflare/alchemy 0.27.4 → 0.29.0

package/src/paperless/errors.ts

@@ -1,62 +0,0 @@
-/**
- * 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/matching-identity.test.ts

@@ -1,194 +0,0 @@
-/**
- * Regression suite for the PR 163 red-team HIGH finding: `diff`/`reconcile` re-derived identity
- * from `news` alone on every call, so renaming (or re-owning) an already-deployed Tag/
- * DocumentType/StoragePath/CustomField missed the row it previously wrote, POSTed a second
- * object under the new name/owner, and left the original permanently orphaned — while `diff`
- * reported a plain `{action:'update'}`. See `matching.ts`'s header for the fix: once `output` is
- * defined, identity is `output.id`, not `(name, owner)`.
- *
- * ⛔ EVERY TEST HERE FAILS ON THE PRE-FIX `matching.ts` (measured before the fix landed — see the
- *   PR comment this file was introduced with):
- *   - the two rename/re-own tests fail because a second POST fires and `fake.rows('tags').length`
- *     is 2, not 1 (the exact duplicate-and-orphan bug);
- *   - the deleted-out-of-band test fails because `diff` never called `fetchLive` at all when
- *     `output` was ignored the pre-fix way — it silently returns `{action:'update'}`  instead of
- *     refusing;
- *   - the first-create and adopt tests already passed pre-fix (the no-state path was never
- *     broken) and are here to prove the fix does not disturb them.
- *
- * ★ THE LAST `describe` BELOW IS A SECOND ROUND (re-review of this same PR): the d3983ff fix
- *   rewired `diff`/`reconcile` to locate by `output.id`, but left `destroy` locating by
- *   `(name, owner)` alone — the exact pre-fix mechanism, with the exact pre-fix consequence
- *   (silently missing a live-but-renamed row) just on the delete path instead of update. See
- *   `matching.ts`'s `destroy` for the fix this suite proves.
- */
-import { describe, expect, test } from 'bun:test';
-import { paperless } from './client.ts';
-import { type MatchingProps, matchingHandlers, matchingOperations } from './matching.ts';
-import { run, withFake } from './fake-paperless.ts';
-
-interface Props extends MatchingProps {
-  note?: string;
-}
-/** ★ The same minimal spec `matching.test.ts` uses — this suite tests `matching.ts`'s own identity contract, not any one family's wiring. */
-const spec = {
-  attributes: (live: Record<string, unknown>, props: Props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    return {
-      id,
-      name: typeof live['name'] === 'string' ? live['name'] : props.name,
-      note: typeof live['note'] === 'string' ? live['note'] : '',
-      owner: typeof live['owner'] === 'number' ? live['owner'] : undefined,
-    };
-  },
-  collection: 'tags' as const,
-  describe: (props: Props) => `tags ${props.name}`,
-  endpoint: { create: 'paperless:POST /api/tags/', update: 'paperless:PATCH /api/tags/{id}/' },
-  fields: [
-    { key: 'note', live: (r: Record<string, unknown>) => r['note'], prop: (p: Props) => p.note },
-  ],
-};
-
-const writesOf = (fake: { seen: readonly { method: string }[] }) =>
-  fake.seen.filter((s) => s.method !== 'GET');
-
-describe('renaming or re-owning an already-deployed object (PR 163)', () => {
-  test('a rename PATCHes the same id — no POST, no orphan', async () => {
-    await withFake(async (fake) => {
-      const handlers = matchingHandlers(spec);
-      const created = await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-      const before = writesOf(fake).length;
-
-      const renamed = await run(
-        handlers.reconcile({ news: { name: 'Invoices - Renamed' }, output: created }),
-      );
-
-      const writes = writesOf(fake);
-      const newWrites = writes.slice(before);
-      expect(writes.length).toBe(before + 1);
-      expect(newWrites.every((w) => w.method === 'PATCH')).toBe(true);
-      expect(fake.rows('tags').length).toBe(1);
-      expect(renamed?.id).toBe(created?.id);
-      expect(renamed?.name).toBe('Invoices - Renamed');
-    });
-  });
-
-  test('an owner change PATCHes the same id — no POST, no orphan', async () => {
-    await withFake(async (fake) => {
-      const handlers = matchingHandlers(spec);
-      const created = await run(handlers.reconcile({ news: { name: 'Invoices', owner: 7 } }));
-      const before = writesOf(fake).length;
-
-      const reowned = await run(
-        handlers.reconcile({ news: { name: 'Invoices', owner: 9 }, output: created }),
-      );
-
-      const writes = writesOf(fake);
-      expect(writes.length).toBe(before + 1);
-      expect(writes[writes.length - 1]?.method).toBe('PATCH');
-      expect(fake.rows('tags').length).toBe(1);
-      expect(reowned?.id).toBe(created?.id);
-      expect(reowned?.owner).toBe(9);
-    });
-  });
-});
-
-describe('a deleted-out-of-band object (PR 163)', () => {
-  test('diff refuses at plan rather than creating a replacement', async () => {
-    await withFake(async (fake) => {
-      const handlers = matchingHandlers(spec);
-      const created = await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-      await run(paperless('DELETE', `tags/${String(created?.id)}/`));
-
-      await expect(
-        run(handlers.diff({ news: { name: 'Invoices' }, output: created })),
-      ).rejects.toThrow(/no longer exists live|deleted out of band/);
-
-      expect(fake.rows('tags').length).toBe(0);
-    });
-  });
-
-  test('reconcile also refuses, not only diff, if called with no prior diff', async () => {
-    await withFake(async (fake) => {
-      const handlers = matchingHandlers(spec);
-      const created = await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-      await run(paperless('DELETE', `tags/${String(created?.id)}/`));
-
-      await expect(
-        run(handlers.reconcile({ news: { name: 'Invoices' }, output: created })),
-      ).rejects.toThrow(/no longer exists live|deleted out of band/);
-
-      expect(fake.rows('tags').length).toBe(0);
-    });
-  });
-});
-
-describe('the no-state path is unaffected (PR 163)', () => {
-  test('a first create still locates by name', async () => {
-    await withFake(async (fake) => {
-      const handlers = matchingHandlers(spec);
-      await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-
-      const get = fake.seen.find((s) => s.method === 'GET');
-      expect(get?.path).toContain('name__iexact=Invoices');
-      const post = fake.seen.find((s) => s.method === 'POST');
-      expect(post).toBeDefined();
-    });
-  });
-
-  test("adopt (output populated from the engine's own read) locates the id it read, no duplicate", async () => {
-    await withFake(async (fake) => {
-      const ops = matchingOperations(spec);
-      const handlers = matchingHandlers(spec);
-      // A pre-existing object, created out of band — what the engine's `provider.read` (always
-      // called with `output: undefined`) discovers during its adoption probe (`Plan.ts`).
-      await run(paperless('POST', 'tags/', { name: 'Invoices', owner: null }));
-      const readAttrs = await run(ops.read({ name: 'Invoices' }));
-      expect(readAttrs).toBeDefined();
-      if (readAttrs === undefined) throw new Error('unreachable: asserted defined above');
-
-      // The engine forces `action: 'adopted'` through the normal update/reconcile path with
-      // `output: node.state.attr` already the just-read attributes (Apply.ts).
-      const after = await run(
-        handlers.reconcile({ news: { name: 'Invoices' }, output: readAttrs }),
-      );
-
-      expect(fake.rows('tags').length).toBe(1);
-      expect(after?.id).toBe(readAttrs?.id);
-      expect(fake.seen.filter((s) => s.method === 'POST').length).toBe(1);
-    });
-  });
-});
-
-describe('delete locates by output.id, not by (possibly stale) olds.name (re-review)', () => {
-  test('a row renamed out of band is still found and deleted, by id', async () => {
-    await withFake(async (fake) => {
-      const handlers = matchingHandlers(spec);
-      const created = await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-      if (created === undefined) throw new Error('unreachable: reconcile always returns attrs');
-
-      // Nothing this package did — a human (or another tool) renamed the live object directly
-      // in Paperless. State's `olds` still says the OLD name; `output` still holds the real id.
-      await run(paperless('PATCH', `tags/${String(created.id)}/`, { name: 'Renamed Elsewhere' }));
-
-      await run(handlers.delete({ olds: { name: 'Invoices' }, output: created }));
-
-      expect(fake.rows('tags').length).toBe(0);
-      const deletes = fake.seen.filter((s) => s.method === 'DELETE');
-      expect(deletes.length).toBe(1);
-      expect(deletes[0]?.path).toBe(`/api/tags/${String(created.id)}/`);
-    });
-  });
-
-  test('with no output (no-state path), delete still falls back to locating by name', async () => {
-    await withFake(async (fake) => {
-      const handlers = matchingHandlers(spec);
-      await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-
-      await run(handlers.delete({ olds: { name: 'Invoices' } }));
-
-      expect(fake.rows('tags').length).toBe(0);
-    });
-  });
-});

package/src/paperless/matching.test.ts

@@ -1,128 +0,0 @@
-/**
- * `matching.ts`'s generic lifecycle against a fake Paperless: owner injection, the version
- * header, 403-never-absent, case-sensitive identity inside a case-insensitive locate, and
- * Unowned-on-every-match (H1).
- *
- * ⛔ THESE TESTS FAIL WITHOUT THE UNIT. `matching.ts`, `client.ts`, `credentials.ts` and
- *   `errors.ts` did not exist before this change — there was nothing to import.
- */
-import { Unowned } from 'alchemy/AdoptPolicy';
-import { describe, expect, test } from 'bun:test';
-import { run, runFailure, withFake } from './fake-paperless.ts';
-import { type MatchingProps, matchingHandlers, matchingOperations } from './matching.ts';
-
-interface Props extends MatchingProps {
-  note?: string;
-}
-/** ★ A minimal spec — this file tests `matching.ts`'s own contract, not any one family's wiring. */
-const spec = {
-  attributes: (live: Record<string, unknown>, props: Props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    return {
-      id,
-      name: typeof live['name'] === 'string' ? live['name'] : props.name,
-      note: typeof live['note'] === 'string' ? live['note'] : '',
-      owner: typeof live['owner'] === 'number' ? live['owner'] : undefined,
-    };
-  },
-  collection: 'tags' as const,
-  describe: (props: Props) => `tags ${props.name}`,
-  endpoint: { create: 'paperless:POST /api/tags/', update: 'paperless:PATCH /api/tags/{id}/' },
-  fields: [
-    { key: 'note', live: (r: Record<string, unknown>) => r['note'], prop: (p: Props) => p.note },
-  ],
-};
-
-describe('create always carries owner, null when undeclared', () => {
-  test('a create with no owner prop sends owner: null', async () => {
-    await withFake(async (fake) => {
-      const handlers = matchingHandlers(spec);
-      await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-      const post = fake.seen.find((s) => s.method === 'POST');
-      expect(post).toBeDefined();
-      expect(JSON.parse(post?.body ?? '{}')).toMatchObject({ name: 'Invoices', owner: null });
-    });
-  });
-
-  test('a create with an owner prop sends that owner', async () => {
-    await withFake(async (fake) => {
-      const handlers = matchingHandlers(spec);
-      await run(handlers.reconcile({ news: { name: 'Receipts', owner: 7 } }));
-      const post = fake.seen.find((s) => s.method === 'POST');
-      expect(JSON.parse(post?.body ?? '{}')).toMatchObject({ owner: 7 });
-    });
-  });
-});
-
-test('every request carries Accept: application/json; version=10', async () => {
-  await withFake(async (fake) => {
-    const handlers = matchingHandlers(spec);
-    await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-    expect(fake.seen.length).toBeGreaterThan(0);
-    for (const call of fake.seen) {
-      expect(call.headers.get('Accept')).toBe('application/json; version=10');
-    }
-  });
-});
-
-test('a no-drift reconcile makes zero writes', async () => {
-  await withFake(async (fake) => {
-    const handlers = matchingHandlers(spec);
-    await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-    const before = fake.seen.filter((s) => s.method !== 'GET').length;
-    await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-    const after = fake.seen.filter((s) => s.method !== 'GET').length;
-    expect(after).toBe(before);
-  });
-});
-
-test('a 403 fails rather than reading as absent', async () => {
-  await withFake(async (fake) => {
-    const ops = matchingOperations(spec);
-    fake.forceStatus = 403;
-    const error = await runFailure(ops.read({ name: 'Invoices' }));
-    expect((error as { _tag?: string })._tag).toBe('PaperlessUnauthorized');
-  });
-});
-
-test('a 404 on read folds to absent (create is the right plan)', async () => {
-  await withFake(async () => {
-    const ops = matchingOperations(spec);
-    expect(await run(ops.read({ name: 'Nothing here' }))).toBeUndefined();
-  });
-});
-
-describe('case-insensitive locate, case-sensitive identity', () => {
-  test('two differently-cased names never collapse into one object', async () => {
-    await withFake(async (fake) => {
-      const handlers = matchingHandlers(spec);
-      await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-      await run(handlers.reconcile({ news: { name: 'invoices' } }));
-      expect(fake.rows('tags').length).toBe(2);
-
-      const ops = matchingOperations(spec);
-      const exact = await run(ops.read({ name: 'Invoices' }));
-      expect(exact?.name).toBe('Invoices');
-      const other = await run(ops.read({ name: 'invoices' }));
-      expect(other?.name).toBe('invoices');
-    });
-  });
-});
-
-test('read answers Unowned on a match, even one identical to the declaration (H1)', async () => {
-  await withFake(async () => {
-    const handlers = matchingHandlers(spec);
-    await run(handlers.reconcile({ news: { name: 'Invoices' } }));
-    const result = await run(handlers.read({ olds: { name: 'Invoices' } }));
-    expect(result).toBeDefined();
-    expect(Unowned.is(result)).toBe(true);
-  });
-});
-
-test('read answers undefined, not Unowned, when nothing matches', async () => {
-  await withFake(async () => {
-    const handlers = matchingHandlers(spec);
-    expect(await run(handlers.read({ olds: { name: 'Nothing here' } }))).toBeUndefined();
-  });
-});