@kelpie/server 0.1.0

package/dist/lib/errors.js

@@ -0,0 +1,102 @@
+/**
+ * The one error type services throw and routes render. Wire shape and status
+ * usage are fixed by `api.md`; this module is the only place that mapping lives.
+ */
+const statusByCode = {
+    bad_request: 400,
+    unauthorized: 401,
+    forbidden: 403,
+    not_found: 404,
+    // Extends the api.md status list, for the MCP transport. Its Streamable HTTP
+    // spec fixes 405 as the answer a server gives for the methods it does not
+    // offer, and a client reads it as "stop trying" rather than "try again".
+    method_not_allowed: 405,
+    conflict: 409,
+    // Extends the api.md status list: the plan does not include this, which is
+    // neither a role problem nor a conflict. 402 would imply Kelpie takes payment,
+    // which a self-hosted install does not.
+    entitlement_required: 403,
+    validation_failed: 422,
+    rate_limited: 429,
+    internal_error: 500,
+};
+export class AppError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'AppError';
+        this.code = code;
+        this.status = statusByCode[code];
+        this.details = details;
+    }
+    static notFound(message = 'Not found') {
+        return new AppError('not_found', message);
+    }
+    static unauthorized(message = 'Missing or invalid credentials') {
+        return new AppError('unauthorized', message);
+    }
+    static validationFailed(message, details) {
+        return new AppError('validation_failed', message, details);
+    }
+    static conflict(message, details) {
+        return new AppError('conflict', message, details);
+    }
+}
+/**
+ * Renders an `AppError` into the wire body from `api.md`. `details` is omitted
+ * rather than sent as null when the error carries none.
+ */
+export function toErrorBody(error) {
+    return {
+        error: error.details === undefined
+            ? { code: error.code, message: error.message }
+            : { code: error.code, message: error.message, details: error.details },
+    };
+}
+/**
+ * The body sent for anything thrown that is not an `AppError`. The real cause is
+ * logged server-side; the client is told nothing about it.
+ */
+export function internalErrorBody() {
+    return { error: { code: 'internal_error', message: 'Internal server error' } };
+}
+/** Renders a parse failure as `path: message`, or just the message at the root. */
+export function describeValidationIssue(issue) {
+    const path = issue.path.map(String).join('.');
+    return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+}
+/**
+ * Turns parse failures into the field-level `details` of a `422` response.
+ *
+ * An unrecognised key is reported against the key itself. Zod raises it at the
+ * object, so its path is empty, and `details` is where a client looks to find out
+ * which field it got wrong.
+ */
+export function toErrorDetails(issues) {
+    return issues.flatMap((issue) => {
+        if (issue.code === 'unrecognized_keys' && issue.keys !== undefined) {
+            const prefix = issue.path.map(String).join('.');
+            return issue.keys.map((key) => ({
+                field: prefix.length > 0 ? `${prefix}.${key}` : key,
+                message: 'Unknown field',
+            }));
+        }
+        return [{ field: issue.path.map(String).join('.'), message: issue.message }];
+    });
+}
+/**
+ * Renders an unknown thrown value as one diagnostic line. Driver errors often
+ * carry an empty `message` and put the useful part in `name` or `code`, so all
+ * three are included.
+ */
+export function describeThrown(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const code = 'code' in error && typeof error.code === 'string' ? error.code : '';
+    const parts = [error.name, code, error.message].filter((part) => part.length > 0);
+    return parts.join(': ');
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"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"}

package/dist/lib/http.d.ts

@@ -0,0 +1,59 @@
+import type { Context } from 'hono';
+import type { z } from 'zod';
+import type { ListQueryParameters, Page } from './pagination.ts';
+/** The parsing every route repeats: read the wire, reject it, or hand back a typed value. */
+/**
+ * Where unauthenticated routes mount (`architecture.md` boot step 5).
+ *
+ * Shared because two places need to agree on it: the app mounts the public
+ * routers here, and a module that builds an absolute URL to one of its own
+ * public endpoints has to spell the same prefix.
+ */
+export declare const PUBLIC_ROUTE_PREFIX = "/v1/public";
+/**
+ * The scheme and host a request arrived on.
+ *
+ * Used to build absolute URLs a customer pastes into their own site. It follows
+ * the request rather than configuration, so it is right wherever the service is
+ * reached from and needs no new environment variable. Behind a proxy it is only
+ * right if that proxy preserves the external `Host`, which is the same condition
+ * every redirect and cookie domain already depends on.
+ */
+export declare function requestOrigin(context: Context): string;
+/**
+ * Reads and validates a JSON request body.
+ *
+ * @throws AppError 400 when the body is not JSON at all, 422 when it is JSON the
+ *   schema refuses. The two are different client mistakes and `api.md` gives them
+ *   different statuses.
+ */
+export declare function readJsonBody<T>(context: Context, schema: z.ZodType<T>): Promise<T>;
+/** Lifts `?limit=`, `?sort=` and `?cursor=` off a request. Validated where the sort fields are known. */
+export declare function readListParameters(context: Context): ListQueryParameters;
+/**
+ * The most ids one filter may name, matching the `?limit=` ceiling in `api.md`.
+ *
+ * The two are the same number on purpose. A caller resolving a page of records
+ * asks about at most one page of ids, so a filter that allowed fewer would make
+ * the maximum page size unusable, and one that allowed more would invite a query
+ * no page could have produced.
+ */
+export declare const MAX_FILTER_IDS = 200;
+/**
+ * Reads an id filter that may be given more than once: `?person_id=a&person_id=b`.
+ *
+ * Repeated parameters rather than a comma-separated list, because an id needs no
+ * escaping this way and there is no separator to get wrong. One occurrence is
+ * the ordinary case and reads the same as it always did.
+ *
+ * @returns The ids, or undefined when the parameter is absent.
+ * @throws AppError 422 for a blank value or more than `MAX_FILTER_IDS` of them.
+ *   Silently dropping either would answer a different question than the one asked.
+ */
+export declare function readIdFilter(context: Context, name: string): readonly string[] | undefined;
+/** The `{ data, next_cursor }` envelope from `api.md`. */
+export declare function pageBody<T>(page: Page<T>, render: (item: T) => Record<string, unknown>): {
+    data: Record<string, unknown>[];
+    next_cursor: string | null;
+};
+//# sourceMappingURL=http.d.ts.map

package/dist/lib/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/lib/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAG5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEhE,6FAA6F;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,eAAe,CAAA;AAE/C;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAEtD;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAWxF;AAED,yGAAyG;AACzG,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAMxE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,MAAM,CAAA;AAEjC;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAoB1F;AAED,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,CAAC,EACxB,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAEjE"}

package/dist/lib/http.js

@@ -0,0 +1,89 @@
+import { AppError, toErrorDetails } from './errors.js';
+/** The parsing every route repeats: read the wire, reject it, or hand back a typed value. */
+/**
+ * Where unauthenticated routes mount (`architecture.md` boot step 5).
+ *
+ * Shared because two places need to agree on it: the app mounts the public
+ * routers here, and a module that builds an absolute URL to one of its own
+ * public endpoints has to spell the same prefix.
+ */
+export const PUBLIC_ROUTE_PREFIX = '/v1/public';
+/**
+ * The scheme and host a request arrived on.
+ *
+ * Used to build absolute URLs a customer pastes into their own site. It follows
+ * the request rather than configuration, so it is right wherever the service is
+ * reached from and needs no new environment variable. Behind a proxy it is only
+ * right if that proxy preserves the external `Host`, which is the same condition
+ * every redirect and cookie domain already depends on.
+ */
+export function requestOrigin(context) {
+    return new URL(context.req.url).origin;
+}
+/**
+ * Reads and validates a JSON request body.
+ *
+ * @throws AppError 400 when the body is not JSON at all, 422 when it is JSON the
+ *   schema refuses. The two are different client mistakes and `api.md` gives them
+ *   different statuses.
+ */
+export async function readJsonBody(context, schema) {
+    const raw = await context.req.json().catch(() => {
+        throw new AppError('bad_request', 'Body must be valid JSON');
+    });
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success) {
+        throw AppError.validationFailed('Request body is invalid', toErrorDetails(parsed.error.issues));
+    }
+    return parsed.data;
+}
+/** Lifts `?limit=`, `?sort=` and `?cursor=` off a request. Validated where the sort fields are known. */
+export function readListParameters(context) {
+    return {
+        limit: context.req.query('limit'),
+        sort: context.req.query('sort'),
+        cursor: context.req.query('cursor'),
+    };
+}
+/**
+ * The most ids one filter may name, matching the `?limit=` ceiling in `api.md`.
+ *
+ * The two are the same number on purpose. A caller resolving a page of records
+ * asks about at most one page of ids, so a filter that allowed fewer would make
+ * the maximum page size unusable, and one that allowed more would invite a query
+ * no page could have produced.
+ */
+export const MAX_FILTER_IDS = 200;
+/**
+ * Reads an id filter that may be given more than once: `?person_id=a&person_id=b`.
+ *
+ * Repeated parameters rather than a comma-separated list, because an id needs no
+ * escaping this way and there is no separator to get wrong. One occurrence is
+ * the ordinary case and reads the same as it always did.
+ *
+ * @returns The ids, or undefined when the parameter is absent.
+ * @throws AppError 422 for a blank value or more than `MAX_FILTER_IDS` of them.
+ *   Silently dropping either would answer a different question than the one asked.
+ */
+export function readIdFilter(context, name) {
+    const values = context.req.queries(name);
+    if (values === undefined || values.length === 0) {
+        return undefined;
+    }
+    if (values.some((value) => value.length === 0)) {
+        throw AppError.validationFailed(`"${name}" cannot be blank`, [
+            { field: name, message: 'Expected an id' },
+        ]);
+    }
+    if (values.length > MAX_FILTER_IDS) {
+        throw AppError.validationFailed(`"${name}" takes at most ${String(MAX_FILTER_IDS)} ids`, [
+            { field: name, message: `Given ${String(values.length)}` },
+        ]);
+    }
+    return values;
+}
+/** The `{ data, next_cursor }` envelope from `api.md`. */
+export function pageBody(page, render) {
+    return { data: page.items.map(render), next_cursor: page.nextCursor };
+}
+//# sourceMappingURL=http.js.map

package/dist/lib/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/lib/http.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGtD,6FAA6F;AAE7F;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAA;AAE/C;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAA;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,OAAgB,EAAE,MAAoB;IAC1E,MAAM,GAAG,GAAY,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;QACvD,MAAM,IAAI,QAAQ,CAAC,aAAa,EAAE,yBAAyB,CAAC,CAAA;IAC9D,CAAC,CAAC,CAAA;IACF,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;IAEpC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,QAAQ,CAAC,gBAAgB,CAAC,yBAAyB,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;IACjG,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAA;AACpB,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC;QACjC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC;QAC/B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC;KACpC,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAA;AAEjC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,IAAY;IACzD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAExC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAC/C,MAAM,QAAQ,CAAC,gBAAgB,CAAC,IAAI,IAAI,mBAAmB,EAAE;YAC3D,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,EAAE;SAC3C,CAAC,CAAA;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;QACnC,MAAM,QAAQ,CAAC,gBAAgB,CAAC,IAAI,IAAI,mBAAmB,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE;YACvF,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE;SAC3D,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,QAAQ,CACtB,IAAa,EACb,MAA4C;IAE5C,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,UAAU,EAAE,CAAA;AACvE,CAAC"}

package/dist/lib/ids.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Identifiers are `<prefix>_<ulid>`. This table is the single source of the
+ * prefixes documented in `api.md`; nothing else may hardcode one.
+ */
+export declare const idPrefixes: {
+    readonly workspace: 'ws';
+    readonly user: 'usr';
+    readonly session: 'ses';
+    readonly passwordResetToken: 'pwr';
+    readonly teamMember: 'mem';
+    readonly invite: 'inv';
+    readonly apiKey: 'key';
+    readonly person: 'per';
+    readonly company: 'com';
+    readonly position: 'pos';
+    readonly pipelineStage: 'stage';
+    readonly deal: 'deal';
+    readonly opportunity: 'opp';
+    readonly partnership: 'prt';
+    readonly raise: 'rse';
+    readonly role: 'role';
+    readonly candidate: 'cand';
+    readonly planItem: 'plan';
+    readonly decision: 'dec';
+    readonly note: 'note';
+    readonly activity: 'act';
+    readonly handbookPage: 'hb';
+    readonly form: 'form';
+    readonly formField: 'ff';
+    readonly formSubmission: 'sub';
+    readonly webhook: 'wh';
+    /** One settled delivery. `api.md` gained the prefix with the delivery log. */
+    readonly webhookDelivery: 'whd';
+    readonly agentRegistration: 'ag';
+    readonly agentRun: 'run';
+    readonly importJob: 'imp';
+    readonly integrationConnection: 'int';
+    /** Never returns over the wire either: identified by `(workspace_id, module_id)` instead. */
+    readonly moduleSetting: 'mset';
+    /**
+     * `idempotency_keys` has no routes of its own and never returns this id over
+     * the wire, so it is not in `api.md`'s public prefix table. It still comes
+     * from this factory rather than a bare `ulid()` call, so every id in the
+     * database is generated the same, injectable way.
+     */
+    readonly idempotencyKey: 'idem';
+};
+export type ObjectKind = keyof typeof idPrefixes;
+export type IdFactory = (kind: ObjectKind) => string;
+/**
+ * Builds the id factory. The ULID generator is injected so tests can pin ids;
+ * production passes nothing and gets time-ordered ULIDs.
+ */
+export declare function createIdFactory(generateUlid?: () => string): IdFactory;
+//# sourceMappingURL=ids.d.ts.map

package/dist/lib/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,UAAU;aACrB,SAAS,EAAE,IAAI;aACf,IAAI,EAAE,KAAK;aACX,OAAO,EAAE,KAAK;aACd,kBAAkB,EAAE,KAAK;aACzB,UAAU,EAAE,KAAK;aACjB,MAAM,EAAE,KAAK;aACb,MAAM,EAAE,KAAK;aACb,MAAM,EAAE,KAAK;aACb,OAAO,EAAE,KAAK;aACd,QAAQ,EAAE,KAAK;aACf,aAAa,EAAE,OAAO;aACtB,IAAI,EAAE,MAAM;aACZ,WAAW,EAAE,KAAK;aAClB,WAAW,EAAE,KAAK;aAClB,KAAK,EAAE,KAAK;aACZ,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;aAChB,QAAQ,EAAE,KAAK;aACf,IAAI,EAAE,MAAM;aACZ,QAAQ,EAAE,KAAK;aACf,YAAY,EAAE,IAAI;aAClB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,IAAI;aACf,cAAc,EAAE,KAAK;aACrB,OAAO,EAAE,IAAI;IACb,8EAA8E;aAC9E,eAAe,EAAE,KAAK;aACtB,iBAAiB,EAAE,IAAI;aACvB,QAAQ,EAAE,KAAK;aACf,SAAS,EAAE,KAAK;aAChB,qBAAqB,EAAE,KAAK;IAC5B,6FAA6F;aAC7F,aAAa,EAAE,MAAM;IACrB;;;;;OAKG;aACH,cAAc,EAAE,MAAM;CACd,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAA;AAEhD,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAA;AAEpD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,GAAE,MAAM,MAAa,GAAG,SAAS,CAE5E"}

package/dist/lib/ids.js

@@ -0,0 +1,56 @@
+import { ulid } from 'ulid';
+/**
+ * Identifiers are `<prefix>_<ulid>`. This table is the single source of the
+ * prefixes documented in `api.md`; nothing else may hardcode one.
+ */
+export const idPrefixes = {
+    workspace: 'ws',
+    user: 'usr',
+    session: 'ses',
+    passwordResetToken: 'pwr',
+    teamMember: 'mem',
+    invite: 'inv',
+    apiKey: 'key',
+    person: 'per',
+    company: 'com',
+    position: 'pos',
+    pipelineStage: 'stage',
+    deal: 'deal',
+    opportunity: 'opp',
+    partnership: 'prt',
+    raise: 'rse',
+    role: 'role',
+    candidate: 'cand',
+    planItem: 'plan',
+    decision: 'dec',
+    note: 'note',
+    activity: 'act',
+    handbookPage: 'hb',
+    form: 'form',
+    formField: 'ff',
+    formSubmission: 'sub',
+    webhook: 'wh',
+    /** One settled delivery. `api.md` gained the prefix with the delivery log. */
+    webhookDelivery: 'whd',
+    agentRegistration: 'ag',
+    agentRun: 'run',
+    importJob: 'imp',
+    integrationConnection: 'int',
+    /** Never returns over the wire either: identified by `(workspace_id, module_id)` instead. */
+    moduleSetting: 'mset',
+    /**
+     * `idempotency_keys` has no routes of its own and never returns this id over
+     * the wire, so it is not in `api.md`'s public prefix table. It still comes
+     * from this factory rather than a bare `ulid()` call, so every id in the
+     * database is generated the same, injectable way.
+     */
+    idempotencyKey: 'idem',
+};
+/**
+ * Builds the id factory. The ULID generator is injected so tests can pin ids;
+ * production passes nothing and gets time-ordered ULIDs.
+ */
+export function createIdFactory(generateUlid = ulid) {
+    return (kind) => `${idPrefixes[kind]}_${generateUlid()}`;
+}
+//# sourceMappingURL=ids.js.map

package/dist/lib/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,SAAS,EAAE,IAAI;IACf,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,KAAK;IACd,kBAAkB,EAAE,KAAK;IACzB,UAAU,EAAE,KAAK;IACjB,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,KAAK;IACf,aAAa,EAAE,OAAO;IACtB,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,KAAK;IAClB,KAAK,EAAE,KAAK;IACZ,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,MAAM;IACjB,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,KAAK;IACf,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,IAAI;IAClB,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,KAAK;IACrB,OAAO,EAAE,IAAI;IACb,8EAA8E;IAC9E,eAAe,EAAE,KAAK;IACtB,iBAAiB,EAAE,IAAI;IACvB,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,KAAK;IAChB,qBAAqB,EAAE,KAAK;IAC5B,6FAA6F;IAC7F,aAAa,EAAE,MAAM;IACrB;;;;;OAKG;IACH,cAAc,EAAE,MAAM;CACd,CAAA;AAMV;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,YAAY,GAAiB,IAAI;IAC/D,OAAO,CAAC,IAAgB,EAAU,EAAE,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,YAAY,EAAE,EAAE,CAAA;AAC9E,CAAC"}

package/dist/lib/logger.d.ts

@@ -0,0 +1,22 @@
+import type { LogLevel } from './config.ts';
+/**
+ * Structured logging as JSON lines. The sink is injected so tests capture output
+ * instead of writing to stdout, and so a deployment can redirect it.
+ */
+export type LogFields = Readonly<Record<string, unknown>>;
+export interface Logger {
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    /** Returns a logger that stamps `fields` onto every line, e.g. a request id. */
+    child(fields: LogFields): Logger;
+}
+export type LogSink = (line: string) => void;
+/**
+ * @param level Minimum level to emit. Lines below it are dropped.
+ * @param sink Receives one complete JSON line per log call.
+ * @param now Injected so tests get deterministic timestamps.
+ */
+export declare function createLogger(level: LogLevel, sink?: LogSink, now?: () => Date): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/lib/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C;;;GAGG;AAEH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEzD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAChD,gFAAgF;IAChF,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAA;CACjC;AAED,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAa5C;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,QAAQ,EACf,IAAI,GAAE,OAAuB,EAC7B,GAAG,GAAE,MAAM,IAAuB,GACjC,MAAM,CAgCR"}

package/dist/lib/logger.js

@@ -0,0 +1,43 @@
+const severityByLevel = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+function writeToStdout(line) {
+    process.stdout.write(`${line}\n`);
+}
+/**
+ * @param level Minimum level to emit. Lines below it are dropped.
+ * @param sink Receives one complete JSON line per log call.
+ * @param now Injected so tests get deterministic timestamps.
+ */
+export function createLogger(level, sink = writeToStdout, now = () => new Date()) {
+    const threshold = severityByLevel[level];
+    function build(boundFields) {
+        function emit(lineLevel, message, fields) {
+            if (severityByLevel[lineLevel] < threshold) {
+                return;
+            }
+            // The envelope is written last so a field called `message`, `level`, or
+            // `time` cannot overwrite it. A colliding field is dropped; a corrupted
+            // envelope would make the whole line untrustworthy.
+            sink(JSON.stringify({
+                ...boundFields,
+                ...fields,
+                time: now().toISOString(),
+                level: lineLevel,
+                message,
+            }));
+        }
+        return {
+            debug: (message, fields) => emit('debug', message, fields),
+            info: (message, fields) => emit('info', message, fields),
+            warn: (message, fields) => emit('warn', message, fields),
+            error: (message, fields) => emit('error', message, fields),
+            child: (fields) => build({ ...boundFields, ...fields }),
+        };
+    }
+    return build({});
+}
+//# sourceMappingURL=logger.js.map

package/dist/lib/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAoBA,MAAM,eAAe,GAAuC;IAC1D,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACV,CAAA;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAA;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAe,EACf,IAAI,GAAY,aAAa,EAC7B,GAAG,GAAe,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;IAElC,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;IAExC,SAAS,KAAK,CAAC,WAAsB;QACnC,SAAS,IAAI,CAAC,SAAmB,EAAE,OAAe,EAAE,MAAkB;YACpE,IAAI,eAAe,CAAC,SAAS,CAAC,GAAG,SAAS,EAAE,CAAC;gBAC3C,OAAM;YACR,CAAC;YACD,wEAAwE;YACxE,wEAAwE;YACxE,oDAAoD;YACpD,IAAI,CACF,IAAI,CAAC,SAAS,CAAC;gBACb,GAAG,WAAW;gBACd,GAAG,MAAM;gBACT,IAAI,EAAE,GAAG,EAAE,CAAC,WAAW,EAAE;gBACzB,KAAK,EAAE,SAAS;gBAChB,OAAO;aACR,CAAC,CACH,CAAA;QACH,CAAC;QAED,OAAO;YACL,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;YAC1D,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC;YACxD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC;YACxD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;YAC1D,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,WAAW,EAAE,GAAG,MAAM,EAAE,CAAC;SACxD,CAAA;IACH,CAAC;IAED,OAAO,KAAK,CAAC,EAAE,CAAC,CAAA;AAClB,CAAC"}

package/dist/lib/moduleConfig.d.ts

@@ -0,0 +1,14 @@
+/** Thrown when a configured path exists but does not hold a valid module config file. */
+export declare class ModuleConfigFileError extends Error {
+    constructor(path: string, reason: string);
+}
+/**
+ * @param path Absolute or relative path, normally `KELPIE_MODULE_CONFIG_PATH`.
+ *   Undefined when the deployment sets no path, which is the ordinary case: a
+ *   workspace's own settings decide instead.
+ * @returns The module id to enabled map the file declares, or undefined when no
+ *   path was given.
+ * @throws ModuleConfigFileError if a given path cannot be read or parsed.
+ */
+export declare function readModuleConfigFile(path: string | undefined): Readonly<Record<string, boolean>> | undefined;
+//# sourceMappingURL=moduleConfig.d.ts.map

package/dist/lib/moduleConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleConfig.d.ts","sourceRoot":"","sources":["../../src/lib/moduleConfig.ts"],"names":[],"mappings":"AAoBA,yFAAyF;AACzF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAGvC;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CA4B5G"}

package/dist/lib/moduleConfig.js

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+/**
+ * Reads `modules.md`'s deploy-time module override file, the mechanism a
+ * self-hoster uses to lock a module on or off for every workspace the process
+ * serves, ahead of whatever a workspace's own settings screen would otherwise
+ * decide (`runtime/moduleConfig.ts` is where that override wins).
+ *
+ * Shape:
+ * ```json
+ * { "modules": { "raises": false, "hiring": false } }
+ * ```
+ */
+const moduleConfigFileSchema = z.object({
+    modules: z.record(z.string(), z.boolean()),
+});
+/** Thrown when a configured path exists but does not hold a valid module config file. */
+export class ModuleConfigFileError extends Error {
+    constructor(path, reason) {
+        super(`${path} is not a valid module config file: ${reason}`);
+        this.name = 'ModuleConfigFileError';
+    }
+}
+/**
+ * @param path Absolute or relative path, normally `KELPIE_MODULE_CONFIG_PATH`.
+ *   Undefined when the deployment sets no path, which is the ordinary case: a
+ *   workspace's own settings decide instead.
+ * @returns The module id to enabled map the file declares, or undefined when no
+ *   path was given.
+ * @throws ModuleConfigFileError if a given path cannot be read or parsed.
+ */
+export function readModuleConfigFile(path) {
+    if (path === undefined) {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new ModuleConfigFileError(path, error instanceof Error ? error.message : String(error));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new ModuleConfigFileError(path, error instanceof Error ? error.message : String(error));
+    }
+    const result = moduleConfigFileSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new ModuleConfigFileError(path, result.error.issues.map((issue) => issue.message).join('; '));
+    }
+    return result.data.modules;
+}
+//# sourceMappingURL=moduleConfig.js.map

package/dist/lib/moduleConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleConfig.js","sourceRoot":"","sources":["../../src/lib/moduleConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;GAUG;AAEH,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;CAC3C,CAAC,CAAA;AAEF,yFAAyF;AACzF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,IAAY,EAAE,MAAc;QACtC,KAAK,CAAC,GAAG,IAAI,uCAAuC,MAAM,EAAE,CAAC,CAAA;QAC7D,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,IAAI,GAAW,CAAA;IAEf,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAClC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,IAAI,qBAAqB,CAAC,IAAI,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IAC/F,CAAC;IAED,IAAI,MAAe,CAAA;IAEnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,IAAI,qBAAqB,CAAC,IAAI,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IAC/F,CAAC;IAED,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;IAEvD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IACrG,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAA;AAC5B,CAAC"}

package/dist/lib/normalisation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Values stored in a normalised form, per `schema.md`. The columns are `citext`
+ * as a second line of defence, so a missed normalisation still compares
+ * correctly rather than creating a duplicate.
+ *
+ * Blank normalises to null rather than to `''`. Both columns are unique within a
+ * workspace, so a stored empty string would make the second record without an
+ * address a 409.
+ */
+export declare function normaliseEmail(raw: string): string | null;
+/**
+ * Reduces a domain to its host: no scheme, no path, no trailing dot.
+ *
+ * Deliberately permissive. This normalises what was given; it does not decide
+ * whether the domain resolves, and a CRM regularly holds a company whose site is
+ * not up yet.
+ */
+export declare function normaliseDomain(raw: string): string | null;
+//# sourceMappingURL=normalisation.d.ts.map

package/dist/lib/normalisation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalisation.d.ts","sourceRoot":"","sources":["../../src/lib/normalisation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIzD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS1D"}

package/dist/lib/normalisation.js

@@ -0,0 +1,32 @@
+/**
+ * Values stored in a normalised form, per `schema.md`. The columns are `citext`
+ * as a second line of defence, so a missed normalisation still compares
+ * correctly rather than creating a duplicate.
+ *
+ * Blank normalises to null rather than to `''`. Both columns are unique within a
+ * workspace, so a stored empty string would make the second record without an
+ * address a 409.
+ */
+/** A scheme prefix: `https://`, `mailto:` and anything else shaped like one. */
+const SCHEME = /^[a-z][a-z0-9+.-]*:\/\//u;
+export function normaliseEmail(raw) {
+    const email = raw.trim().toLowerCase();
+    return email.length === 0 ? null : email;
+}
+/**
+ * Reduces a domain to its host: no scheme, no path, no trailing dot.
+ *
+ * Deliberately permissive. This normalises what was given; it does not decide
+ * whether the domain resolves, and a CRM regularly holds a company whose site is
+ * not up yet.
+ */
+export function normaliseDomain(raw) {
+    const host = raw
+        .trim()
+        .toLowerCase()
+        .replace(SCHEME, '')
+        .split('/')[0]
+        ?.replace(/\.$/u, '');
+    return host === undefined || host.length === 0 ? null : host;
+}
+//# sourceMappingURL=normalisation.js.map

package/dist/lib/normalisation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalisation.js","sourceRoot":"","sources":["../../src/lib/normalisation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gFAAgF;AAChF,MAAM,MAAM,GAAG,0BAA0B,CAAA;AAEzC,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAEtC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAA;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,IAAI,GAAG,GAAG;SACb,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACnB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACd,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAEvB,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;AAC9D,CAAC"}