@homeflare/alchemy 0.27.4 → 0.29.0

package/dist/paperless/client.d.ts

@@ -1,37 +0,0 @@
-/**
- * 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 { PaperlessCredentials, type PaperlessCredentialsError } from './credentials.ts';
-import { type PaperlessError } from './errors.ts';
-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 declare const paperless: <T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: Record<string, unknown>) => Effect.Effect<T, PaperlessError | PaperlessCredentialsError, PaperlessRequirements>;
-//# sourceMappingURL=client.d.ts.map

package/dist/paperless/client.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/paperless/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAE9D,OAAO,EAAE,oBAAoB,EAAE,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,EAAE,KAAK,cAAc,EAAuC,MAAM,aAAa,CAAC;AAKvF,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;CAChC;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,UAAU,GAAG,oBAAoB,CAAC;AAEjF,6FAA6F;AAC7F,eAAO,MAAM,SAAS,GAAI,CAAC,UACjB,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,QAC7C,MAAM,SACL,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,cAAc,GAAG,yBAAyB,EAAE,qBAAqB,CAwCjF,CAAC"}

package/dist/paperless/credentials.d.ts

@@ -1,40 +0,0 @@
-/**
- * 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 Effect from 'effect/Effect';
-import * as Layer from 'effect/Layer';
-declare const PaperlessCredentialsError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "PaperlessCredentialsError";
-} & Readonly<A>;
-export declare class PaperlessCredentialsError extends PaperlessCredentialsError_base<{
-    readonly message: string;
-}> {
-}
-export interface PaperlessCredentialValue {
-    /** Trailing slash stripped, e.g. `https://paperless.example.com`. */
-    readonly url: string;
-    readonly token: string;
-}
-declare const PaperlessCredentials_base: Context.ServiceClass<PaperlessCredentials, "PaperlessCredentials", Effect.Effect<PaperlessCredentialValue, PaperlessCredentialsError, never>>;
-/**
- * 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 declare class PaperlessCredentials extends PaperlessCredentials_base {
-}
-export declare const environmentLayer: Layer.Layer<PaperlessCredentials>;
-export {};
-//# sourceMappingURL=credentials.d.ts.map

package/dist/paperless/credentials.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/paperless/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAE1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;;;;AAEtC,qBAAa,yBAA0B,SAAQ,+BAA8C;IAC3F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;CAAG;AAEL,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;;AA4BD;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,yBAGf;CAAG;AAE9B,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,KAAK,CAAC,oBAAoB,CAG9D,CAAC"}

package/dist/paperless/errors.d.ts

@@ -1,49 +0,0 @@
-declare const PaperlessNotFound_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "PaperlessNotFound";
-} & Readonly<A>;
-/** No object at that path. The only tag `matching.ts` folds to "absent". */
-export declare class PaperlessNotFound extends PaperlessNotFound_base<{
-    readonly method: string;
-    readonly path: string;
-}> {
-}
-declare const PaperlessUnauthorized_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "PaperlessUnauthorized";
-} & Readonly<A>;
-/** 401 (no/bad token) or 403 (token valid, forbidden) — NEVER read as "the object is absent". */
-export declare class PaperlessUnauthorized extends PaperlessUnauthorized_base<{
-    readonly status: 401 | 403;
-    readonly method: string;
-    readonly path: string;
-}> {
-}
-declare const PaperlessValidation_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "PaperlessValidation";
-} & Readonly<A>;
-/** 400 — the vendor rejected the body. Carries it, so the message quotes Paperless's own words. */
-export declare class PaperlessValidation extends PaperlessValidation_base<{
-    readonly method: string;
-    readonly path: string;
-    readonly body: string;
-}> {
-}
-declare const PaperlessUnavailable_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "PaperlessUnavailable";
-} & Readonly<A>;
-/** 5xx, or a status this family's endpoints do not otherwise document. */
-export declare class PaperlessUnavailable extends PaperlessUnavailable_base<{
-    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 declare const statusToError: (status: number, method: string, path: string, body: string) => PaperlessError;
-export {};
-//# sourceMappingURL=errors.d.ts.map

package/dist/paperless/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/paperless/errors.ts"],"names":[],"mappings":";;;AAYA,4EAA4E;AAC5E,qBAAa,iBAAkB,SAAQ,uBAAsC;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;CAAG;;;;AAEL,iGAAiG;AACjG,qBAAa,qBAAsB,SAAQ,2BAA0C;IACnF,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;CAAG;;;;AAEL,mGAAmG;AACnG,qBAAa,mBAAoB,SAAQ,yBAAwC;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;CAAG;;;;AAEL,0EAA0E;AAC1E,qBAAa,oBAAqB,SAAQ,0BAAyC;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;CAAG;AAEL,MAAM,MAAM,cAAc,GACtB,iBAAiB,GACjB,qBAAqB,GACrB,mBAAmB,GACnB,oBAAoB,CAAC;AAEzB;;;;GAIG;AACH,eAAO,MAAM,aAAa,WAChB,MAAM,UACN,MAAM,QACR,MAAM,QACN,MAAM,KACX,cAKF,CAAC"}

package/src/litellm/client.ts

@@ -1,195 +0,0 @@
-/**
- * The four LiteLLM proxy calls a `LiteLLM.PassThroughEndpoint` needs, and nothing else reaches
- * LiteLLM's `/config/pass_through_endpoint` routes.
- *
- * ⛔ WRAPPED IN A PER-BASE-URL SEMAPHORE. LiteLLM stores every pass-through endpoint in ONE
- *   `general_settings.pass_through_endpoints` list (pass_through_endpoints.py at tag v1.100.0),
- *   so create/update/delete are each a read-modify-write of the WHOLE list through
- *   `update_config_general_settings`. Two of this package's own calls racing each other — two
- *   endpoints created in the same deploy — would each read the list, add their own row and write
- *   it back, and the second write would silently drop the first row. One permit per proxy
- *   serialises this package's own writes; it cannot serialise against the LiteLLM UI or a second
- *   deploy process, which is why `reconcile` reads back after writing rather than trusting the
- *   call that just returned (docs/litellm.md).
- * ★ `Authorization: Bearer <key>` — LiteLLM's own client uses it (litellm/proxy/client/cli, and
- *   every `/config/*` route decorator at the tag takes `user_api_key_dict = Depends(user_api_key_auth)`,
- *   which accepts a bearer token). Every mutation additionally requires the caller be
- *   PROXY_ADMIN (`update_config_general_settings`, proxy_server.py:16411 at the tag) — an
- *   ordinary virtual key gets `LitellmUnauthorizedError`, not a clearer 403 body naming the role.
- * ⛔ NO MESSAGE SNIFFING (S21). Every status this file maps becomes a typed tag; nothing here or
- *   above it matches an error body's text. Deleting an id LiteLLM does not have answers 400
- *   (measured against the tag's `pass_through_endpoint_delete` — the id is looked up in the list
- *   and a miss raises `HTTPException(400)`, not 404) — but so does a genuinely-live row when the
- *   caller isn't PROXY_ADMIN, or the DB is disconnected (`update_config_general_settings`,
- *   proxy_server.py:16389-16416 at the tag): the SAME status, for a delete that did NOT happen.
- *   `deletePassThroughEndpoint` tells them apart by re-listing (a GET, which needs no PROXY_ADMIN —
- *   proxy_server.py:3245-3251) rather than by the 400's body text — see its own comment.
- */
-import * as Data from 'effect/Data';
-import * as Effect from 'effect/Effect';
-import * as HttpClient from 'effect/unstable/http/HttpClient';
-import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
-import * as Semaphore from 'effect/Semaphore';
-import { LitellmCredentials, type LitellmCredentialsError } from './credentials.ts';
-import type {
-  PassThroughEndpointResponse,
-  PassThroughGenericEndpoint,
-} from './generated/pass-through.ts';
-
-export type LitellmRequirements = HttpClient.HttpClient | LitellmCredentials;
-
-/**
- * The `litellm:<METHOD> <path>` operations this package writes to and reads from.
- *
- * ★ `codegen/litellm.ts` scans this FILE's text for these exact literals to pick which of
- *   LiteLLM 1.100.0's 696 paths to generate types from (codegen/litellm.ts header). Keep each one
- *   a literal string on one line; the generator matches text, it does not evaluate the object.
- */
-export const LITELLM_OPERATIONS = {
-  create: 'litellm:POST /config/pass_through_endpoint',
-  delete: 'litellm:DELETE /config/pass_through_endpoint',
-  list: 'litellm:GET /config/pass_through_endpoint',
-  update: 'litellm:POST /config/pass_through_endpoint/{endpoint_id}',
-} as const;
-
-export class LitellmUnauthorizedError extends Data.TaggedError('LitellmUnauthorizedError')<{
-  readonly status: number;
-  readonly method: string;
-  readonly path: string;
-}> {}
-export class LitellmBadRequestError extends Data.TaggedError('LitellmBadRequestError')<{
-  readonly method: string;
-  readonly path: string;
-  readonly detail: string;
-}> {}
-export class LitellmHttpError extends Data.TaggedError('LitellmHttpError')<{
-  readonly status: number;
-  readonly method: string;
-  readonly path: string;
-  readonly detail: string;
-}> {}
-export class LitellmTransportError extends Data.TaggedError('LitellmTransportError')<{
-  readonly method: string;
-  readonly path: string;
-  readonly cause: string;
-}> {}
-
-export type LitellmError =
-  | LitellmUnauthorizedError
-  | LitellmBadRequestError
-  | LitellmHttpError
-  | LitellmTransportError
-  | LitellmCredentialsError;
-
-const semaphores = new Map<string, Semaphore.Semaphore>();
-
-/** One semaphore per base URL, created on first use. Never `Hash.structure` (S18) — a plain Map key. */
-const semaphoreFor = (baseUrl: string): Effect.Effect<Semaphore.Semaphore> =>
-  Effect.sync(() => {
-    const existing = semaphores.get(baseUrl);
-    if (existing !== undefined) return existing;
-    const created = Semaphore.makeUnsafe(1);
-    semaphores.set(baseUrl, created);
-    return created;
-  });
-
-const call = <T>(method: 'GET' | 'POST' | 'DELETE', path: string, body?: unknown) =>
-  Effect.gen(function* () {
-    const creds = yield* yield* LitellmCredentials;
-    const client = yield* HttpClient.HttpClient;
-    const url = `${creds.baseUrl}${path}`;
-    const request = HttpClientRequest.make(method)(url).pipe(
-      HttpClientRequest.setHeaders({
-        Accept: 'application/json',
-        Authorization: `Bearer ${creds.apiKey}`,
-      }),
-      body === undefined
-        ? (self) => self
-        : HttpClientRequest.bodyText(JSON.stringify(body), 'application/json'),
-    );
-    const response = yield* client
-      .execute(request)
-      .pipe(
-        Effect.mapError(
-          (cause) => new LitellmTransportError({ cause: String(cause), method, path }),
-        ),
-      );
-    const text = yield* response.text.pipe(
-      Effect.mapError((cause) => new LitellmTransportError({ cause: String(cause), method, path })),
-    );
-    if (response.status === 401 || response.status === 403) {
-      return yield* Effect.fail(
-        new LitellmUnauthorizedError({ method, path, status: response.status }),
-      );
-    }
-    if (response.status === 400) {
-      return yield* Effect.fail(
-        new LitellmBadRequestError({ detail: text.slice(0, 300), method, path }),
-      );
-    }
-    if (response.status < 200 || response.status >= 300) {
-      return yield* Effect.fail(
-        new LitellmHttpError({ detail: text.slice(0, 300), method, path, status: response.status }),
-      );
-    }
-    return (text === '' ? undefined : JSON.parse(text)) as T;
-  });
-
-/** GET /config/pass_through_endpoint — every row, config-file and DB alike. Not under the semaphore: reads don't race the field. */
-export const listPassThroughEndpoints = (): Effect.Effect<
-  readonly PassThroughGenericEndpoint[],
-  LitellmError,
-  LitellmRequirements
-> =>
-  call<PassThroughEndpointResponse>('GET', '/config/pass_through_endpoint').pipe(
-    Effect.map((body) => body.endpoints),
-  );
-
-const mutate = <T>(io: Effect.Effect<T, LitellmError, LitellmRequirements>) =>
-  Effect.gen(function* () {
-    const creds = yield* yield* LitellmCredentials;
-    const semaphore = yield* semaphoreFor(creds.baseUrl);
-    return yield* semaphore.withPermits(1)(io);
-  });
-
-/** POST /config/pass_through_endpoint. `body` carries `id` — see pass-through-endpoint.ts. */
-export const createPassThroughEndpoint = (
-  body: PassThroughGenericEndpoint,
-): Effect.Effect<void, LitellmError, LitellmRequirements> =>
-  mutate(call('POST', '/config/pass_through_endpoint', body));
-
-/** POST /config/pass_through_endpoint/{endpoint_id}. Merges with `exclude_none` — see pass-through-form.ts. */
-export const updatePassThroughEndpoint = (
-  endpointId: string,
-  body: Partial<PassThroughGenericEndpoint>,
-): Effect.Effect<void, LitellmError, LitellmRequirements> =>
-  mutate(call('POST', `/config/pass_through_endpoint/${encodeURIComponent(endpointId)}`, body));
-
-/**
- * DELETE /config/pass_through_endpoint?endpoint_id=… — idempotent BY THIS FUNCTION, not by the
- * vendor. ⚠️ Measured at v1.100.0: deleting an id the list does not have raises `HTTPException(400)`
- * from `pass_through_endpoint_delete` — but the SAME route also 400s `not_allowed_access` for a
- * non-PROXY_ADMIN caller or a disconnected DB (`update_config_general_settings`,
- * proxy_server.py:16389-16416), on a row that never got deleted. A 400 alone cannot tell the two
- * apart, so THIS FUNCTION DOESN'T GUESS FROM THE STATUS ALONE: on 400 it re-lists (a GET — no
- * PROXY_ADMIN required, proxy_server.py:3245-3251) and only treats the delete as already-done if
- * `endpointId` is genuinely absent; otherwise the delete failed and this re-fails with the ORIGINAL
- * error, not a message match (S21 — a status-and-a-real-read decision, never body text).
- */
-export const deletePassThroughEndpoint = (
-  endpointId: string,
-): Effect.Effect<void, LitellmError, LitellmRequirements> =>
-  mutate(
-    call(
-      'DELETE',
-      `/config/pass_through_endpoint?endpoint_id=${encodeURIComponent(endpointId)}`,
-    ).pipe(
-      Effect.catchTag('LitellmBadRequestError', (original) =>
-        Effect.gen(function* () {
-          const rows = yield* listPassThroughEndpoints();
-          if (rows.some((row) => row.id === endpointId)) return yield* Effect.fail(original);
-        }),
-      ),
-      Effect.asVoid,
-    ),
-  );

package/src/litellm/credentials.ts

@@ -1,73 +0,0 @@
-/**
- * The lazy Auth service every LiteLLM call reads from, and nothing else reads the environment.
- *
- * ★ LITELLM'S OWN VARIABLE NAMES, NOT A HOUSE CHOICE. `LITELLM_PROXY_URL` and
- *   `LITELLM_PROXY_API_KEY` are what LiteLLM's own CLI client reads
- *   (litellm/proxy/client/cli/main.py:70,78 at tag v1.100.0) — using the vendor's own names means
- *   a consumer who already has a `.env` for the `litellm` CLI needs nothing new for this package.
- * ⛔ NO DEFAULT URL. A published package that fell back to a loopback address would let a
- *   consumer who forgot the variable watch every call fail against a proxy that is not theirs,
- *   instead of being told which variable is missing (S24/S25 — the house rule, not a vendor one).
- * ⛔ THE KEY IS NEVER A PROP. Alchemy persists attributes unencrypted (S25); the master key that
- *   `update_config_general_settings` requires (PROXY_ADMIN only, proxy_server.py:16411 at the
- *   tag) is read fresh from the environment on every call, never stored in state.
- * ★ LAZY: the service's VALUE is an `Effect` that resolves the credential, not the credential
- *   itself — so a layer built once still reads the environment inside each operation
- *   (`yield* yield* LitellmCredentials`), the idiom `alchemy/Auth`'s custom-auth-provider guide
- *   describes for a credential a layer must not capture at build time.
- */
-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 const LITELLM_PROXY_URL_ENV = 'LITELLM_PROXY_URL';
-export const LITELLM_PROXY_API_KEY_ENV = 'LITELLM_PROXY_API_KEY';
-
-export interface LitellmCreds {
-  /** Trailing slash stripped. No default — see the header. */
-  readonly baseUrl: string;
-  /** LiteLLM's master (or a PROXY_ADMIN) key. Never logged, never an attribute. */
-  readonly apiKey: string;
-}
-
-export class LitellmCredentialsError extends Data.TaggedError('LitellmCredentialsError')<{
-  readonly message: string;
-}> {}
-
-const missing = (name: string): LitellmCredentialsError =>
-  new LitellmCredentialsError({
-    message:
-      `${name} is not set. Export it — the same variable LiteLLM's own \`litellm\` CLI ` +
-      'reads — before running a stack that declares a LiteLLM.PassThroughEndpoint.',
-  });
-
-/** Read at call time. Exported so a test can call it directly against `process.env`. */
-export const resolveCreds: Effect.Effect<LitellmCreds, LitellmCredentialsError> = Effect.gen(
-  function* () {
-    const rawUrl = process.env[LITELLM_PROXY_URL_ENV];
-    if (rawUrl === undefined || rawUrl.trim() === '')
-      return yield* Effect.fail(missing(LITELLM_PROXY_URL_ENV));
-    const rawKey = process.env[LITELLM_PROXY_API_KEY_ENV];
-    if (rawKey === undefined || rawKey.trim() === '') {
-      return yield* Effect.fail(missing(LITELLM_PROXY_API_KEY_ENV));
-    }
-    return { baseUrl: rawUrl.trim().replace(/\/$/, ''), apiKey: rawKey.trim() };
-  },
-);
-
-/** The Effect service a LiteLLM operation reads: `yield* yield* LitellmCredentials`. */
-export class LitellmCredentials extends Context.Service<
-  LitellmCredentials,
-  Effect.Effect<LitellmCreds, LitellmCredentialsError>
->()('homeflare/litellm/Credentials') {}
-
-/** The default layer: resolves from the environment, fresh, on every `yield*`. */
-export const litellmCredentialsLayer: Layer.Layer<LitellmCredentials> = Layer.succeed(
-  LitellmCredentials,
-  resolveCreds,
-);
-
-/** For a test: a fixed credential, never touching the environment. */
-export const litellmCredentialsLayerFor = (creds: LitellmCreds): Layer.Layer<LitellmCredentials> =>
-  Layer.succeed(LitellmCredentials, Effect.succeed(creds));

package/src/litellm/generated/pass-through.ts

@@ -1,73 +0,0 @@
-/**
- * Generated from LiteLLM 1.100.0's OpenAPI document -- DO NOT EDIT BY HAND.
- *
- * Run: bun codegen/litellm.ts    (`--check` compares without writing)
- * Manifest entry: `litellm-openapi` -- LiteLLM Proxy (app.openapi()) 1.100.0
- *   sha256 1b3e4d23da6aea92..., read from codegen/manifest.json's own note on how this document
- *   was produced (the vendor's own generator, cross-checked byte-identically — not a live read).
- *
- * Covers the 4 pass-through operations this package writes to:
- *   litellm:DELETE /config/pass_through_endpoint
- *   litellm:GET /config/pass_through_endpoint
- *   litellm:POST /config/pass_through_endpoint
- *   litellm:POST /config/pass_through_endpoint/{endpoint_id}
- *
- * Does NOT cover the other 692 paths LiteLLM 1.100.0 publishes — this generator is
- * consumer-driven (codegen/litellm.ts), not exhaustive. See codegen/README.md.
- */
-
-export interface PassThroughEndpointResponse {
-  readonly endpoints: readonly PassThroughGenericEndpoint[];
-}
-
-export interface PassThroughGenericEndpoint {
-  /**
-   * Whether authentication is required for the pass-through endpoint. Defaults to True so a pass-through silently created without an explicit value still requires a valid LiteLLM API key — set to False only if the endpoint is meant to be a public forwarder (e.g. an unauthenticated webhook target).
-   * @default true
-   */
-  readonly auth?: boolean;
-  /**
-   * The USD cost per request to the target endpoint. This is used to calculate the cost of the request to the target endpoint.
-   * @default 0
-   */
-  readonly cost_per_request?: number;
-  /**
-   * Key-value pairs of default query parameters to be sent with every request to this endpoint. These can be overridden by client-provided query parameters. For example: {'key': 'default_value', 'api_version': '2023-01'}
-   * @default {}
-   */
-  readonly default_query_params?: Record<string, unknown>;
-  /** Guardrails configuration for this passthrough endpoint. Dict keys are guardrail names, values are optional settings for field targeting. When set, all org/team/key level guardrails will also execute. Defaults to None (no guardrails execute). */
-  readonly guardrails?: Record<string, PassThroughGuardrailSettings | null> | null;
-  /**
-   * Key-value pairs of headers to be forwarded with the request. You can set any key value pair here and it will be forwarded to your target endpoint
-   * @default {}
-   */
-  readonly headers?: Record<string, unknown>;
-  /** Optional unique identifier for the pass-through endpoint. If not provided, endpoints will be identified by path for backwards compatibility. */
-  readonly id?: string | null;
-  /**
-   * If True, requests to subpaths of the path will be forwarded to the target endpoint. For example, if the path is /bria and include_subpath is True, requests to /bria/v1/text-to-image/base/2.3 will be forwarded to the target endpoint.
-   * @default false
-   */
-  readonly include_subpath?: boolean;
-  /**
-   * True if this endpoint is defined in the config file, False if from DB. Config-defined endpoints cannot be edited via the UI.
-   * @default false
-   */
-  readonly is_from_config?: boolean;
-  /** List of HTTP methods this endpoint handles (e.g., ['GET', 'POST']). If None or empty, all methods (GET, POST, PUT, DELETE, PATCH) are supported for backward compatibility. This allows the same path to have different targets for different HTTP methods. */
-  readonly methods?: readonly string[] | null;
-  /** The route to be added to the LiteLLM Proxy Server. */
-  readonly path: string;
-  /** The URL to which requests for this path should be forwarded. */
-  readonly target: string;
-  /** Upstream request timeout in seconds for this pass-through endpoint. If unset, uses general_settings.pass_through_request_timeout (default 600). */
-  readonly timeout?: number | null;
-}
-
-export interface PassThroughGuardrailSettings {
-  /** JSONPath expressions for input field targeting (pre_call). Examples: 'query', 'documents[*].text', 'messages[*].content'. If not specified, guardrail runs on entire request payload. */
-  readonly request_fields?: readonly string[] | null;
-  /** JSONPath expressions for output field targeting (post_call). Examples: 'results[*].text', 'output'. If not specified, guardrail runs on entire response payload. */
-  readonly response_fields?: readonly string[] | null;
-}

package/src/paperless/client.ts

@@ -1,88 +0,0 @@
-/**
- * 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/credentials.ts

@@ -1,69 +0,0 @@
-/**
- * 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,
-);