@satorio/machinery 0.2.1

package/dist/http/health.d.ts

@@ -0,0 +1,70 @@
+import { Effect, Exit } from 'effect';
+/**
+ * The path that answers whether this process is alive at all, without checking
+ * a single dependency.
+ */
+export declare const LIVEZ_PATH = "/livez";
+/**
+ * The path that answers whether this service can take traffic, after every
+ * mounted dependency has been asked.
+ */
+export declare const READYZ_PATH = "/readyz";
+/**
+ * Same check as READYZ_PATH, under a second name. Orchestrators expect
+ * different words for the same question: can you send traffic here.
+ */
+export declare const HEALTHZ_PATH = "/healthz";
+/**
+ * How one dependency came back: it answered, or it is down.
+ */
+export type HealthCheckStatus = 'ok' | 'down';
+/**
+ * One dependency to check, under the name the answer reports it by.
+ */
+export interface NamedHealthCheck<R> {
+    readonly name: string;
+    readonly verify: Effect.Effect<void, unknown, R>;
+}
+/**
+ * What the readiness endpoint answers: whether the service is ready, and how
+ * each dependency came back.
+ */
+export interface ReadinessOutcome {
+    readonly ready: boolean;
+    readonly checks: Readonly<Record<string, HealthCheckStatus>>;
+}
+/**
+ * Runs a readiness check and returns its Exit. A resolver borrows the same
+ * shape from the runtime as the GraphQL context does, so both sides of the
+ * machinery talk to the runtime through one interface.
+ */
+export type RunHealthCheck<R> = <A, E>(program: Effect.Effect<A, E, R>) => Promise<Exit.Exit<A, E>>;
+/**
+ * How long one check gets before it counts as down. Without a deadline a
+ * check that hangs, rather than failing outright, keeps /readyz open
+ * indefinitely instead of returning in time.
+ */
+export declare const DEFAULT_HEALTH_CHECK_DEADLINE_MILLIS = 3000;
+/**
+ * What the readiness routes need: the runtime that runs a check, the checks
+ * themselves, and the deadline one check gets.
+ */
+export interface HealthRoutesOptions<R> {
+    readonly runCheck: RunHealthCheck<R>;
+    readonly checks: readonly NamedHealthCheck<R>[];
+    readonly checkDeadlineMillis?: number;
+}
+/**
+ * Runs every check independently, in parallel, under its own deadline. One
+ * dependency that fails or hangs does not hide the others' results and does
+ * not hold /readyz open past checkDeadlineMillis. An empty checks list
+ * reports ready: true — an app with no mounted dependencies is ready by
+ * itself.
+ */
+export declare const checkReadiness: <R>(options: HealthRoutesOptions<R>) => Effect.Effect<ReadinessOutcome>;
+/**
+ * Handles the three readiness endpoints. Returns null on any other path, so
+ * the caller passes the request on down its own chain — one Bun.serve
+ * handler can then serve both readiness probes and GraphQL.
+ */
+export declare const healthRoutesFetch: <R>(options: HealthRoutesOptions<R>) => ((request: Request) => Promise<Response | null>);

package/dist/http/health.js

@@ -0,0 +1,60 @@
+import { Duration, Effect, Exit } from 'effect';
+/**
+ * The path that answers whether this process is alive at all, without checking
+ * a single dependency.
+ */
+export const LIVEZ_PATH = '/livez';
+/**
+ * The path that answers whether this service can take traffic, after every
+ * mounted dependency has been asked.
+ */
+export const READYZ_PATH = '/readyz';
+/**
+ * Same check as READYZ_PATH, under a second name. Orchestrators expect
+ * different words for the same question: can you send traffic here.
+ */
+export const HEALTHZ_PATH = '/healthz';
+/**
+ * How long one check gets before it counts as down. Without a deadline a
+ * check that hangs, rather than failing outright, keeps /readyz open
+ * indefinitely instead of returning in time.
+ */
+export const DEFAULT_HEALTH_CHECK_DEADLINE_MILLIS = 3_000;
+const oneCheckOutcome = (runCheck, check, deadlineMillis) => Effect.promise(() => runCheck(check.verify.pipe(Effect.timeout(Duration.millis(deadlineMillis))))).pipe(Effect.map((exit) => [check.name, Exit.isSuccess(exit) ? 'ok' : 'down']));
+/**
+ * Runs every check independently, in parallel, under its own deadline. One
+ * dependency that fails or hangs does not hide the others' results and does
+ * not hold /readyz open past checkDeadlineMillis. An empty checks list
+ * reports ready: true — an app with no mounted dependencies is ready by
+ * itself.
+ */
+export const checkReadiness = (options) => {
+    const deadlineMillis = options.checkDeadlineMillis ?? DEFAULT_HEALTH_CHECK_DEADLINE_MILLIS;
+    return Effect.forEach(options.checks, (check) => oneCheckOutcome(options.runCheck, check, deadlineMillis), { concurrency: 'unbounded' }).pipe(Effect.map((pairs) => {
+        const checks = Object.fromEntries(pairs);
+        const ready = pairs.every(([, status]) => status === 'ok');
+        return { ready, checks };
+    }));
+};
+const jsonResponse = (status, body) => new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+});
+/**
+ * Handles the three readiness endpoints. Returns null on any other path, so
+ * the caller passes the request on down its own chain — one Bun.serve
+ * handler can then serve both readiness probes and GraphQL.
+ */
+export const healthRoutesFetch = (options) => {
+    return async (request) => {
+        const url = new URL(request.url);
+        if (url.pathname === LIVEZ_PATH) {
+            return jsonResponse(200, { status: 'ok' });
+        }
+        if (url.pathname === READYZ_PATH || url.pathname === HEALTHZ_PATH) {
+            const outcome = await Effect.runPromise(checkReadiness(options));
+            return jsonResponse(outcome.ready ? 200 : 503, outcome);
+        }
+        return null;
+    };
+};

package/dist/http/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Public entry to the http mechanism: readiness probes mounted on the same port
+ * as GraphQL. See machinery/graphql/server.ts for where they attach.
+ */
+export { checkReadiness, DEFAULT_HEALTH_CHECK_DEADLINE_MILLIS, HEALTHZ_PATH, type HealthCheckStatus, type HealthRoutesOptions, healthRoutesFetch, LIVEZ_PATH, type NamedHealthCheck, READYZ_PATH, type ReadinessOutcome, type RunHealthCheck, } from './health.js';

package/dist/http/index.js

@@ -0,0 +1,5 @@
+/**
+ * Public entry to the http mechanism: readiness probes mounted on the same port
+ * as GraphQL. See machinery/graphql/server.ts for where they attach.
+ */
+export { checkReadiness, DEFAULT_HEALTH_CHECK_DEADLINE_MILLIS, HEALTHZ_PATH, healthRoutesFetch, LIVEZ_PATH, READYZ_PATH, } from './health.js';

package/dist/identifiers/client-code.d.ts

@@ -0,0 +1,37 @@
+import { Effect, Either } from 'effect';
+import { NotAClientCodeError } from './failures.js';
+declare const clientCodeBrand: unique symbol;
+/**
+ * The number a client quotes back to you: eight digits, the last of which
+ * checks the other seven. It is a label and never an identity — the
+ * identity of an account is its own identifier — and it is never a key of
+ * anything either, so knowing one opens nothing.
+ */
+export type ClientCode = string & {
+    readonly [clientCodeBrand]: 'ClientCode';
+};
+/**
+ * A fresh client code, drawn from the randomness the service already
+ * shares. The seven drawn digits never start with a zero, so the code
+ * reads back the same whether a person writes it or a spreadsheet does,
+ * and the eighth digit is the check the whole code stands on. Nothing
+ * here counts: two codes issued one after the other say nothing about
+ * how many clients came between them.
+ */
+export declare const newClientCode: Effect.Effect<ClientCode>;
+/**
+ * Reads a client code somebody typed, forgiving the spaces and hyphens a
+ * person puts between the groups. A code whose check digit does not hold
+ * comes back as a refusal, and the refusal names no character.
+ */
+export declare const clientCodeFrom: (text: string) => Either.Either<ClientCode, NotAClientCodeError>;
+/**
+ * The eight digits with nothing between them, which is the form a
+ * document number and a payment reference are built from.
+ */
+export declare const digitsOfClientCode: (code: ClientCode) => string;
+/**
+ * The form a person reads off a document: two groups of four.
+ */
+export declare const clientCodeInGroupedForm: (code: ClientCode) => string;
+export {};

package/dist/identifiers/client-code.js

@@ -0,0 +1,41 @@
+import { Effect, Either, Random } from 'effect';
+import { dammHolds, withDammCheckDigit } from './damm.js';
+import { NotAClientCodeError } from './failures.js';
+const DRAWN_DIGITS = 7;
+const EIGHT_DIGITS_WITHOUT_A_LEADING_ZERO = /^[1-9]\d{7}$/;
+const NOT_A_DIGIT = /[\s-]+/g;
+const GROUP = 4;
+/**
+ * A fresh client code, drawn from the randomness the service already
+ * shares. The seven drawn digits never start with a zero, so the code
+ * reads back the same whether a person writes it or a spreadsheet does,
+ * and the eighth digit is the check the whole code stands on. Nothing
+ * here counts: two codes issued one after the other say nothing about
+ * how many clients came between them.
+ */
+export const newClientCode = Effect.gen(function* () {
+    const first = yield* Random.nextIntBetween(1, 10);
+    const rest = yield* Effect.replicateEffect(Random.nextIntBetween(0, 10), DRAWN_DIGITS - 1);
+    const drawn = `${first}${rest.join('')}`;
+    return (withDammCheckDigit(drawn) ?? drawn);
+});
+/**
+ * Reads a client code somebody typed, forgiving the spaces and hyphens a
+ * person puts between the groups. A code whose check digit does not hold
+ * comes back as a refusal, and the refusal names no character.
+ */
+export const clientCodeFrom = (text) => {
+    const digits = text.replace(NOT_A_DIGIT, '');
+    return EIGHT_DIGITS_WITHOUT_A_LEADING_ZERO.test(digits) && dammHolds(digits)
+        ? Either.right(digits)
+        : Either.left(new NotAClientCodeError({ text }));
+};
+/**
+ * The eight digits with nothing between them, which is the form a
+ * document number and a payment reference are built from.
+ */
+export const digitsOfClientCode = (code) => code;
+/**
+ * The form a person reads off a document: two groups of four.
+ */
+export const clientCodeInGroupedForm = (code) => `${code.slice(0, GROUP)}-${code.slice(GROUP)}`;

package/dist/identifiers/creditor-reference.d.ts

@@ -0,0 +1,38 @@
+import { Either } from 'effect';
+import type { DocumentNumber } from './document-number.js';
+import { NotACreditorReferenceError } from './failures.js';
+declare const creditorReferenceBrand: unique symbol;
+/**
+ * The reference a payer copies into a bank transfer, with its own check
+ * digits.
+ *
+ * The reference a payer copies into their bank transfer: the letters `RF`, two
+ * check digits over everything after them, and the digits of the document
+ * number. It follows ISO 11649, so a bank anywhere reads it and a typo in it
+ * does not reach anybody's ledger.
+ */
+export type CreditorReference = string & {
+    readonly [creditorReferenceBrand]: 'CreditorReference';
+};
+/**
+ * The payment reference for a document that somebody has to pay.
+ */
+export declare const creditorReferenceOf: (number: DocumentNumber) => CreditorReference;
+/**
+ * Reads a reference somebody typed, forgiving case, spaces and the
+ * hyphens a person copies along with it. A reference whose check digits
+ * do not hold comes back as a refusal that names no character: the
+ * payer retypes the whole reference, and nobody guessing at references
+ * learns which part they got closest on.
+ */
+export declare const creditorReferenceFrom: (text: string) => Either.Either<CreditorReference, NotACreditorReferenceError>;
+/**
+ * The digits of the document number this reference points at.
+ */
+export declare const digitsOfCreditorReference: (reference: CreditorReference) => string;
+/**
+ * The form a person reads off a document and types into a bank: groups
+ * of four, the way ISO 11649 prints one.
+ */
+export declare const creditorReferenceInGroupedForm: (reference: CreditorReference) => string;
+export {};

package/dist/identifiers/creditor-reference.js

@@ -0,0 +1,32 @@
+import { Either } from 'effect';
+import { generate, parse } from 'node-iso11649';
+import { digitsOfDocumentNumber } from './document-number.js';
+import { NotACreditorReferenceError } from './failures.js';
+const NOT_A_REFERENCE_CHARACTER = /[\s-]+/g;
+const GROUP = 4;
+/**
+ * The payment reference for a document that somebody has to pay.
+ */
+export const creditorReferenceOf = (number) => generate(digitsOfDocumentNumber(number));
+/**
+ * Reads a reference somebody typed, forgiving case, spaces and the
+ * hyphens a person copies along with it. A reference whose check digits
+ * do not hold comes back as a refusal that names no character: the
+ * payer retypes the whole reference, and nobody guessing at references
+ * learns which part they got closest on.
+ */
+export const creditorReferenceFrom = (text) => {
+    const written = text.replace(NOT_A_REFERENCE_CHARACTER, '').toUpperCase();
+    return parse(written) === null
+        ? Either.left(new NotACreditorReferenceError({ text }))
+        : Either.right(written);
+};
+/**
+ * The digits of the document number this reference points at.
+ */
+export const digitsOfCreditorReference = (reference) => reference.slice(GROUP);
+/**
+ * The form a person reads off a document and types into a bank: groups
+ * of four, the way ISO 11649 prints one.
+ */
+export const creditorReferenceInGroupedForm = (reference) => (reference.match(/.{1,4}/g) ?? [reference]).join(' ');

package/dist/identifiers/damm.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The check digit that makes a run of digits self-checking, by Damm's
+ * algorithm. The table above is the order-ten totally anti-symmetric
+ * quasigroup of the 2004 paper *Total anti-symmetrische Quasigruppen*
+ * (Philipps-Universitat Marburg), which is what makes the digit catch
+ * every single wrong digit and every swap of two neighbours. A text
+ * holding anything but digits gets `null` — the caller turns that into
+ * its own refusal.
+ *
+ * No package on the registry carries this algorithm at a version a
+ * service should depend on, so it stands here as one pure function with
+ * its source named, rather than as an unmaintained peer dependency.
+ */
+export declare const dammCheckDigit: (digits: string) => string | null;
+/**
+ * The same digits with their check digit written on the end.
+ */
+export declare const withDammCheckDigit: (digits: string) => string | null;
+/**
+ * Whether a run of digits already carries a check digit that holds.
+ */
+export declare const dammHolds: (digits: string) => boolean;

package/dist/identifiers/damm.js

@@ -0,0 +1,50 @@
+const OPERATION_TABLE = [
+    [0, 3, 1, 7, 5, 9, 8, 6, 4, 2],
+    [7, 0, 9, 2, 1, 5, 4, 8, 6, 3],
+    [4, 2, 0, 6, 8, 7, 1, 3, 5, 9],
+    [1, 7, 5, 0, 9, 8, 3, 4, 2, 6],
+    [6, 1, 2, 3, 0, 4, 5, 9, 7, 8],
+    [3, 6, 7, 4, 2, 0, 9, 5, 8, 1],
+    [5, 8, 6, 9, 7, 2, 0, 1, 3, 4],
+    [8, 9, 4, 5, 3, 6, 2, 0, 1, 7],
+    [9, 4, 3, 8, 6, 1, 7, 2, 0, 5],
+    [2, 5, 8, 1, 4, 3, 6, 7, 9, 0],
+];
+const ONLY_DIGITS = /^\d+$/;
+const interimOf = (digits) => {
+    if (!ONLY_DIGITS.test(digits))
+        return null;
+    let row = 0;
+    for (const digit of digits) {
+        row = OPERATION_TABLE[row]?.[Number(digit)] ?? 0;
+    }
+    return row;
+};
+/**
+ * The check digit that makes a run of digits self-checking, by Damm's
+ * algorithm. The table above is the order-ten totally anti-symmetric
+ * quasigroup of the 2004 paper *Total anti-symmetrische Quasigruppen*
+ * (Philipps-Universitat Marburg), which is what makes the digit catch
+ * every single wrong digit and every swap of two neighbours. A text
+ * holding anything but digits gets `null` — the caller turns that into
+ * its own refusal.
+ *
+ * No package on the registry carries this algorithm at a version a
+ * service should depend on, so it stands here as one pure function with
+ * its source named, rather than as an unmaintained peer dependency.
+ */
+export const dammCheckDigit = (digits) => {
+    const interim = interimOf(digits);
+    return interim === null ? null : String(interim);
+};
+/**
+ * The same digits with their check digit written on the end.
+ */
+export const withDammCheckDigit = (digits) => {
+    const check = dammCheckDigit(digits);
+    return check === null ? null : `${digits}${check}`;
+};
+/**
+ * Whether a run of digits already carries a check digit that holds.
+ */
+export const dammHolds = (digits) => interimOf(digits) === 0;

package/dist/identifiers/document-number.d.ts

@@ -0,0 +1,68 @@
+import type { ClosedSet } from '@satorio/machinery/core';
+import { type CalendarDay } from '@satorio/machinery/time';
+import { Either } from 'effect';
+import { type ClientCode } from './client-code.js';
+import { NotADocumentNumberError } from './failures.js';
+declare const documentNumberBrand: unique symbol;
+/**
+ * The number printed on a document, in the form a person reads it.
+ *
+ * The number printed on a document: its series, the client code, the reporting
+ * month as two digits of year and two of month, and the count of documents
+ * that client has been sent that month.
+ */
+export type DocumentNumber = string & {
+    readonly [documentNumberBrand]: 'DocumentNumber';
+};
+/**
+ * What a document number is made of. The count is shared across every
+ * series, so a client never meets two documents carrying the same digits
+ * in one month.
+ */
+export interface DocumentNumberParts<Series extends string = string> {
+    readonly series: Series;
+    readonly clientCode: ClientCode;
+    readonly reportingMonth: CalendarDay;
+    readonly count: number;
+}
+/**
+ * The two digits of year and two of month a reporting period is written
+ * as: March 2026 reads `2603`.
+ */
+export declare const reportingMonthOf: (day: CalendarDay) => string;
+/**
+ * Builds a document number out of its parts. A count below one, or one
+ * that is no whole number, comes back as a refusal: a document nobody
+ * counted has no number.
+ *
+ * @internal
+ */
+export declare const documentNumberOf: (parts: DocumentNumberParts) => Either.Either<DocumentNumber, NotADocumentNumberError>;
+/**
+ * Reads a document number somebody typed against the series a service
+ * issues. The series has to stand in that set, and the client code
+ * inside the number has to pass its own check digit, so a number
+ * invented by hand does not read back.
+ *
+ * @internal
+ */
+export declare const documentNumberReadFrom: (text: string, series: ClosedSet<readonly string[]>) => Either.Either<DocumentNumber, NotADocumentNumberError>;
+/**
+ * The series this document belongs to, as the number itself spells it.
+ *
+ * @internal
+ */
+export declare const seriesOfDocumentNumber: (number: DocumentNumber) => string;
+/**
+ * The digits of a document number with the series and the hyphens taken
+ * off, which is what a payment reference is built over.
+ */
+export declare const digitsOfDocumentNumber: (number: DocumentNumber) => string;
+/**
+ * The client code printed inside a document number. Every document
+ * number that exists was either built from a client code or read back
+ * through that code's own check digit, so the eight digits at the front
+ * of one are always a code that holds.
+ */
+export declare const clientCodeOfDocumentNumber: (number: DocumentNumber) => ClientCode;
+export {};

package/dist/identifiers/document-number.js

@@ -0,0 +1,73 @@
+import { dayInIsoForm } from '@satorio/machinery/time';
+import { Either } from 'effect';
+import { clientCodeFrom, clientCodeInGroupedForm, } from './client-code.js';
+import { NotADocumentNumberError } from './failures.js';
+const SMALLEST_COUNT = 1;
+const COUNT_DIGITS = 2;
+const CLIENT_CODE_DIGITS = 8;
+const WRITTEN_FORM = /^([A-Z]{2,3})-(\d{4})-(\d{4})-(\d{4})-(\d{2,})$/;
+const YEAR_IN_MONTH = 4;
+const NOT_A_DIGIT = /[\s-]+/g;
+/**
+ * The two digits of year and two of month a reporting period is written
+ * as: March 2026 reads `2603`.
+ */
+export const reportingMonthOf = (day) => {
+    const iso = dayInIsoForm(day);
+    return `${iso.slice(2, YEAR_IN_MONTH)}${iso.slice(5, 7)}`;
+};
+/**
+ * Builds a document number out of its parts. A count below one, or one
+ * that is no whole number, comes back as a refusal: a document nobody
+ * counted has no number.
+ *
+ * @internal
+ */
+export const documentNumberOf = (parts) => {
+    const counted = Number.isInteger(parts.count) && parts.count >= SMALLEST_COUNT;
+    const count = String(parts.count).padStart(COUNT_DIGITS, '0');
+    const written = `${parts.series}-${clientCodeInGroupedForm(parts.clientCode)}` +
+        `-${reportingMonthOf(parts.reportingMonth)}-${count}`;
+    return counted
+        ? Either.right(written)
+        : Either.left(new NotADocumentNumberError({ text: written }));
+};
+/**
+ * Reads a document number somebody typed against the series a service
+ * issues. The series has to stand in that set, and the client code
+ * inside the number has to pass its own check digit, so a number
+ * invented by hand does not read back.
+ *
+ * @internal
+ */
+export const documentNumberReadFrom = (text, series) => {
+    const written = text.trim().toUpperCase();
+    const parts = WRITTEN_FORM.exec(written);
+    const refused = Either.left(new NotADocumentNumberError({ text }));
+    if (parts === null)
+        return refused;
+    const [, written_series = '', first = '', second = ''] = parts;
+    if (!series.is(written_series))
+        return refused;
+    return Either.isRight(clientCodeFrom(`${first}${second}`))
+        ? Either.right(written)
+        : refused;
+};
+/**
+ * The series this document belongs to, as the number itself spells it.
+ *
+ * @internal
+ */
+export const seriesOfDocumentNumber = (number) => number.slice(0, number.indexOf('-'));
+/**
+ * The digits of a document number with the series and the hyphens taken
+ * off, which is what a payment reference is built over.
+ */
+export const digitsOfDocumentNumber = (number) => number.slice(number.indexOf('-') + 1).replace(NOT_A_DIGIT, '');
+/**
+ * The client code printed inside a document number. Every document
+ * number that exists was either built from a client code or read back
+ * through that code's own check digit, so the eight digits at the front
+ * of one are always a code that holds.
+ */
+export const clientCodeOfDocumentNumber = (number) => digitsOfDocumentNumber(number).slice(0, CLIENT_CODE_DIGITS);

package/dist/identifiers/document-numbers.d.ts

@@ -0,0 +1,27 @@
+import type { ClosedSet } from '@satorio/machinery/core';
+import type { DocumentNumberCounter, DocumentNumberCounterUnavailableError } from '@satorio/machinery/ports';
+import type { Effect, Either } from 'effect';
+import { type DocumentNumber, type DocumentNumberParts } from './document-number.js';
+import type { NotADocumentNumberError } from './failures.js';
+import { type NextDocumentNumberInput } from './next-document-number.js';
+/**
+ * The document numbers of one closed set of series: minting bound to
+ * that set, reading that refuses any series outside it, and the set
+ * itself, so a caller lists its own series in one place and reads them
+ * back from the same one.
+ */
+export interface DocumentNumbers<Series extends readonly string[]> {
+    readonly series: ClosedSet<Series>;
+    readonly of: (parts: DocumentNumberParts<Series[number]>) => Either.Either<DocumentNumber, NotADocumentNumberError>;
+    readonly from: (text: string) => Either.Either<DocumentNumber, NotADocumentNumberError>;
+    readonly seriesOf: (number: DocumentNumber) => Series[number];
+    readonly next: (input: NextDocumentNumberInput<Series[number]>) => Effect.Effect<DocumentNumber, DocumentNumberCounterUnavailableError, DocumentNumberCounter>;
+}
+/**
+ * Binds document numbers to the series one service issues. Which kinds
+ * of document exist is that service's own canon, never this package's:
+ * a proforma, a monthly invoice and a credit note belong to whoever
+ * sends them, and a package that hard-codes those four sends every
+ * other business back to writing its own numbering.
+ */
+export declare const makeDocumentNumbers: <const Series extends readonly string[]>(series: ClosedSet<Series>) => DocumentNumbers<Series>;

package/dist/identifiers/document-numbers.js

@@ -0,0 +1,16 @@
+import { documentNumberOf, documentNumberReadFrom, seriesOfDocumentNumber, } from './document-number.js';
+import { nextDocumentNumber, } from './next-document-number.js';
+/**
+ * Binds document numbers to the series one service issues. Which kinds
+ * of document exist is that service's own canon, never this package's:
+ * a proforma, a monthly invoice and a credit note belong to whoever
+ * sends them, and a package that hard-codes those four sends every
+ * other business back to writing its own numbering.
+ */
+export const makeDocumentNumbers = (series) => ({
+    series,
+    of: (parts) => documentNumberOf(parts),
+    from: (text) => documentNumberReadFrom(text, series),
+    seriesOf: (number) => seriesOfDocumentNumber(number),
+    next: (input) => nextDocumentNumber(input),
+});

package/dist/identifiers/failures.d.ts

@@ -0,0 +1,46 @@
+import type { Refusal } from '@satorio/machinery/core';
+declare const NotAClientCodeError_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: "NotAClientCodeError";
+} & Readonly<A>;
+/**
+ * The text handed in is not a client code. The refusal never says which
+ * character failed: a client code is a public label, and a message that
+ * narrows the search helps whoever is guessing at codes more than it
+ * helps the person who typed one wrong.
+ */
+export declare class NotAClientCodeError extends NotAClientCodeError_base<{
+    readonly text: string;
+}> {
+    get refusal(): Refusal;
+}
+declare const NotADocumentNumberError_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: "NotADocumentNumberError";
+} & Readonly<A>;
+/**
+ * The parts handed in cannot make a document number, or the text handed
+ * in does not read as one.
+ */
+export declare class NotADocumentNumberError extends NotADocumentNumberError_base<{
+    readonly text: string;
+}> {
+    get refusal(): Refusal;
+}
+declare const NotACreditorReferenceError_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: "NotACreditorReferenceError";
+} & Readonly<A>;
+/**
+ * The text handed in is not a payment reference this mechanism issued.
+ * Like a client code, the refusal names no character: whoever typed one
+ * wrong retypes the whole reference, and whoever is guessing learns
+ * nothing.
+ */
+export declare class NotACreditorReferenceError extends NotACreditorReferenceError_base<{
+    readonly text: string;
+}> {
+    get refusal(): Refusal;
+}
+/**
+ * Every way this mechanism refuses a value.
+ */
+export type IdentifierFailure = NotAClientCodeError | NotADocumentNumberError | NotACreditorReferenceError;
+export {};

package/dist/identifiers/failures.js

@@ -0,0 +1,48 @@
+import { Data } from 'effect';
+/**
+ * The text handed in is not a client code. The refusal never says which
+ * character failed: a client code is a public label, and a message that
+ * narrows the search helps whoever is guessing at codes more than it
+ * helps the person who typed one wrong.
+ */
+export class NotAClientCodeError extends Data.TaggedError('NotAClientCodeError') {
+    get refusal() {
+        return {
+            what: `${JSON.stringify(this.text)} is not a client code.`,
+            why: 'A client code is eight digits, the last of which checks the other ' +
+                'seven, and this text does not pass that check.',
+            whatToDo: 'Read the code off the document again, keeping all eight digits, ' +
+                'then hand it back.',
+        };
+    }
+}
+/**
+ * The parts handed in cannot make a document number, or the text handed
+ * in does not read as one.
+ */
+export class NotADocumentNumberError extends Data.TaggedError('NotADocumentNumberError') {
+    get refusal() {
+        return {
+            what: `${JSON.stringify(this.text)} is not a document number.`,
+            why: 'A document number is a series, a client code, the reporting month ' +
+                'as four digits, and a count, joined by hyphens.',
+            whatToDo: 'Write it as INV-4173-8297-2609-02, then hand it back.',
+        };
+    }
+}
+/**
+ * The text handed in is not a payment reference this mechanism issued.
+ * Like a client code, the refusal names no character: whoever typed one
+ * wrong retypes the whole reference, and whoever is guessing learns
+ * nothing.
+ */
+export class NotACreditorReferenceError extends Data.TaggedError('NotACreditorReferenceError') {
+    get refusal() {
+        return {
+            what: `${JSON.stringify(this.text)} is not a payment reference that exists.`,
+            why: 'A payment reference carries its own two check digits, and this ' +
+                'text does not pass them.',
+            whatToDo: 'Copy the reference from the document again, then hand it back.',
+        };
+    }
+}