@kelpie/server 0.1.0

package/dist/modules/forms/submission.js

@@ -0,0 +1,337 @@
+import { AppError } from '../../lib/errors.js';
+import { describeCreationVia, describeFormSubmission } from '../activities/wording.js';
+import * as companyRepository from '../companies/repository.js';
+import * as dealRepository from '../deals/repository.js';
+import * as peopleRepository from '../people/repository.js';
+import * as pipelineRepository from '../pipelines/repository.js';
+import * as positionRepository from '../positions/repository.js';
+import * as workspaceRepository from '../workspace/repository.js';
+import { DEAL_CLOSE_HORIZON_DAYS, companyNameFrom, describeAnswers, expandDealNameTemplate, expectedCloseFrom, fillBlank, findAnswerProblems, mapAnswers, readIntent, } from './mapping.js';
+import * as repository from './repository.js';
+/**
+ * The public submit: `forms.md` rules 1 to 7, server-side.
+ *
+ * This is the port of `processFormSubmission` from `mockups/src/data/seed.ts`.
+ * The pure half of those rules lives in `mapping.ts`; what is left here is the
+ * upserts, in one transaction, so a submission never records a person that was
+ * rolled back.
+ *
+ * Nothing in this file takes an `Actor`. A submit arrives with no credentials,
+ * and the only thing naming a workspace is the form's `publicKey`. Every query
+ * below is scoped to the workspace read off that form.
+ */
+/** What the timeline calls a row a form wrote. */
+const FORM_ACTOR = { kind: 'system', label: 'Form' };
+/**
+ * Used when a form creates deals and nobody wrote a name template.
+ *
+ * The board has to show something, and the company is what a reader of an
+ * inbound deal looks for. The mockup's own default adds " — website"; that
+ * belongs to a form somebody configured, not to the fallback.
+ */
+const DEFAULT_DEAL_NAME_TEMPLATE = '{{company.name}}';
+/**
+ * Defaults for a Company a submit invents, from `forms.md` rule 4.
+ *
+ * `sizeBand` is not in that list and the column is `NOT NULL`, so it takes the
+ * smallest band: the honest reading of a company nobody has told us anything
+ * about yet.
+ */
+const NEW_COMPANY_DEFAULTS = {
+    stage: 'other',
+    sizeBand: '1-10',
+    accountType: 'prospect',
+    icpFit: 'unknown',
+};
+/**
+ * Defaults for a Person a submit invents, from `forms.md`.
+ *
+ * No tags. The mockup tags new records `inbound` and `form`; `forms.md` says the
+ * summary and tags start empty, and provenance is already carried by the
+ * timeline entry and by the FormSubmission's own links.
+ */
+const NEW_PERSON_DEFAULTS = {
+    relationship: 'cold',
+    preferredChannel: 'email',
+    influence: 'influencer',
+};
+/**
+ * One `record.created` per record this submit invented, and one
+ * `record.updated` per record it filled a blank on.
+ *
+ * A submit that matched an existing person and changed nothing about them emits
+ * neither: a consumer mirroring the CRM has nothing to mirror, and
+ * `form.submitted` already says the submission happened.
+ *
+ * The Deal has no `Upserted` because it is only ever created, and its people
+ * link rides along with it rather than as a separate `record.updated`, the same
+ * way the deals service treats a create.
+ */
+function emitRecordEvents(events, workspaceId, touched) {
+    const upserts = [
+        { objectType: 'person', outcome: touched.person },
+        { objectType: 'company', outcome: touched.company },
+        { objectType: 'position', outcome: touched.position },
+    ];
+    for (const { objectType, outcome } of upserts) {
+        if (outcome === undefined) {
+            continue;
+        }
+        if (outcome.created) {
+            events.emit('record.created', { workspaceId, objectType, recordId: outcome.record.id });
+            continue;
+        }
+        if (outcome.filled.length > 0) {
+            events.emit('record.updated', {
+                workspaceId,
+                objectType,
+                recordId: outcome.record.id,
+                changedFields: outcome.filled,
+            });
+        }
+    }
+    if (touched.dealId !== null) {
+        events.emit('record.created', { workspaceId, objectType: 'deal', recordId: touched.dealId });
+    }
+}
+export function createFormSubmitService(dependencies) {
+    /**
+     * Upserts the Person, matched on the normalised address.
+     *
+     * `lastContactedAt` is stamped either way, and unlike every other field it
+     * overwrites: it records when this person was last in touch, and filling the
+     * form in is them being in touch. It is not reported as a filled blank,
+     * because a consumer watching for enrichment does not want a notification
+     * every time somebody says hello.
+     */
+    async function upsertPerson(tx, workspaceId, intent) {
+        const now = dependencies.now();
+        const existing = await peopleRepository.findPersonByEmail(tx, workspaceId, intent.email);
+        if (existing === undefined) {
+            const created = await peopleRepository.insertPerson(tx, {
+                id: dependencies.createId('person'),
+                workspaceId,
+                name: intent.personName,
+                email: intent.email,
+                lastContactedAt: now,
+                ...NEW_PERSON_DEFAULTS,
+            });
+            return { record: created, created: true, filled: [] };
+        }
+        const name = fillBlank(existing.name, intent.personName);
+        const updated = await peopleRepository.updatePerson(tx, workspaceId, existing.id, {
+            ...(name === undefined ? {} : { name }),
+            lastContactedAt: now,
+            updatedAt: now,
+        });
+        if (updated === undefined) {
+            throw new Error(`Person ${existing.id} disappeared during a form submit`);
+        }
+        return { record: updated, created: false, filled: name === undefined ? [] : ['name'] };
+    }
+    /**
+     * Upserts the Company, by domain when there is one and by name otherwise
+     * (`forms.md` rule 4).
+     *
+     * @returns undefined when the answers said nothing about a company, which is
+     *   the ordinary case for a form collecting only a name and an address.
+     */
+    async function upsertCompany(tx, workspaceId, intent) {
+        const name = companyNameFrom(intent);
+        if (name === undefined) {
+            return undefined;
+        }
+        const byDomain = intent.companyDomain === undefined
+            ? undefined
+            : await companyRepository.findCompanyByDomain(tx, workspaceId, intent.companyDomain);
+        const existing = byDomain ??
+            (intent.companyName === undefined
+                ? undefined
+                : await companyRepository.findCompanyByName(tx, workspaceId, intent.companyName));
+        if (existing === undefined) {
+            const created = await companyRepository.insertCompany(tx, {
+                id: dependencies.createId('company'),
+                workspaceId,
+                name,
+                domain: intent.companyDomain ?? null,
+                ...NEW_COMPANY_DEFAULTS,
+            });
+            return { record: created, created: true, filled: [] };
+        }
+        const filledName = fillBlank(existing.name, intent.companyName);
+        const filledDomain = fillBlank(existing.domain, intent.companyDomain);
+        const changes = {
+            ...(filledName === undefined ? {} : { name: filledName }),
+            ...(filledDomain === undefined ? {} : { domain: filledDomain }),
+        };
+        const filled = Object.keys(changes);
+        if (filled.length === 0) {
+            return { record: existing, created: false, filled };
+        }
+        const updated = await companyRepository.updateCompany(tx, workspaceId, existing.id, {
+            ...changes,
+            updatedAt: dependencies.now(),
+        });
+        if (updated === undefined) {
+            throw new Error(`Company ${existing.id} disappeared during a form submit`);
+        }
+        return { record: updated, created: false, filled };
+    }
+    /**
+     * Links the person to the company, if a title arrived.
+     *
+     * A submit never creates a second Position at a company the person already
+     * holds one at. An inbound "VP Sales" from somebody the team recorded as
+     * "Sales Director" is the same job described differently, and two rows would
+     * put them on the company page twice. The stored title wins, as everywhere
+     * else in a submit.
+     */
+    async function upsertPosition(tx, workspaceId, personId, companyId, title) {
+        const held = await positionRepository.listPositionsAt(tx, workspaceId, personId, companyId);
+        const existing = held.find((position) => position.title.toLowerCase() === title.toLowerCase()) ?? held[0];
+        if (existing !== undefined) {
+            return { record: existing, created: false, filled: [] };
+        }
+        const created = await positionRepository.insertPosition(tx, {
+            id: dependencies.createId('position'),
+            workspaceId,
+            personId,
+            companyId,
+            title,
+        });
+        return { record: created, created: true, filled: [] };
+    }
+    /** The stage a form's deals open in: the one it names, or the pipeline's first open one. */
+    async function openingStageId(tx, workspaceId, form) {
+        if (form.dealStageId !== null) {
+            return form.dealStageId;
+        }
+        const stages = await pipelineRepository.listStagesOfKind(tx, workspaceId, 'deal');
+        const first = stages.find((stage) => stage.open) ?? stages[0];
+        if (first === undefined) {
+            // Unreachable through the API: a workspace seeds its stages at creation
+            // and the last stage of a pipeline cannot be removed.
+            throw AppError.conflict('This workspace has no deal stages');
+        }
+        return first.id;
+    }
+    /**
+     * Creates the Deal, when the form makes them and a company was resolved.
+     *
+     * A deal belongs to a company (`deals.company_id` is `NOT NULL`), so a submit
+     * that resolved none creates no deal and says so through a null `deal_id` on
+     * the submission rather than by inventing one.
+     */
+    async function createDeal(tx, workspaceId, form, intent, company, personId) {
+        const id = dependencies.createId('deal');
+        const owner = await workspaceRepository.findDefaultMember(tx, workspaceId);
+        await dealRepository.insertDeal(tx, {
+            id,
+            workspaceId,
+            name: intent.dealName ??
+                expandDealNameTemplate(form.dealNameTemplate ?? DEFAULT_DEAL_NAME_TEMPLATE, {
+                    companyName: company.name,
+                    personName: intent.personName,
+                }),
+            companyId: company.id,
+            stageId: await openingStageId(tx, workspaceId, form),
+            valueCents: 0,
+            currency: null,
+            ownerId: owner?.id ?? null,
+            expectedClose: expectedCloseFrom(dependencies.now(), DEAL_CLOSE_HORIZON_DAYS),
+        });
+        await dealRepository.insertDealPeople(tx, id, [personId]);
+        return id;
+    }
+    /**
+     * The form behind a public key, ready to accept answers.
+     *
+     * @throws AppError 404 for an unknown key, 409 for a paused form (`forms.md`).
+     */
+    async function requireOpenForm(publicKey) {
+        const form = await repository.findFormByPublicKey(dependencies.db, publicKey);
+        // An unknown key is indistinguishable from one whose form was deleted, and
+        // the caller is a website with no credentials: it learns nothing either way.
+        if (form === undefined) {
+            throw AppError.notFound('Form not found');
+        }
+        if (form.status === 'paused') {
+            throw AppError.conflict('This form is not accepting submissions');
+        }
+        return form;
+    }
+    /** @throws AppError 422 listing everything wrong with the answers at once. */
+    function readAnswers(fields, answers) {
+        const problems = findAnswerProblems(fields, answers);
+        if (problems.length > 0) {
+            throw AppError.validationFailed('Those answers are not ones this form accepts', problems);
+        }
+        const intent = readIntent(mapAnswers(fields, answers));
+        if (intent === undefined) {
+            throw AppError.validationFailed('This form needs an email address', [
+                { field: 'answers', message: 'No usable person.email answer' },
+            ]);
+        }
+        return intent;
+    }
+    return {
+        async submit(publicKey, answers) {
+            const form = await requireOpenForm(publicKey);
+            const { workspaceId } = form;
+            const fields = await repository.listFields(dependencies.db, form.id);
+            const intent = readAnswers(fields, answers);
+            return dependencies.transaction(async ({ tx, events }) => {
+                const person = await upsertPerson(tx, workspaceId, intent);
+                const company = await upsertCompany(tx, workspaceId, intent);
+                const position = company === undefined || intent.positionTitle === undefined
+                    ? undefined
+                    : await upsertPosition(tx, workspaceId, person.record.id, company.record.id, intent.positionTitle);
+                const dealId = form.createDeal && company !== undefined
+                    ? await createDeal(tx, workspaceId, form, intent, company.record, person.record.id)
+                    : null;
+                const submission = await repository.insertSubmission(tx, {
+                    id: dependencies.createId('formSubmission'),
+                    workspaceId,
+                    formId: form.id,
+                    answers,
+                    personId: person.record.id,
+                    companyId: company?.record.id ?? null,
+                    positionId: position?.record.id ?? null,
+                    dealId,
+                    submittedAt: dependencies.now(),
+                });
+                await dependencies.recordActivity(tx, workspaceId, FORM_ACTOR, {
+                    targetType: 'person',
+                    targetId: person.record.id,
+                    kind: 'created',
+                    ...describeFormSubmission(form.name, describeAnswers(fields, answers)),
+                });
+                if (dealId !== null) {
+                    await dependencies.recordActivity(tx, workspaceId, FORM_ACTOR, {
+                        targetType: 'deal',
+                        targetId: dealId,
+                        kind: 'created',
+                        ...describeCreationVia('Deal', form.name),
+                    });
+                }
+                emitRecordEvents(events, workspaceId, { person, company, position, dealId });
+                events.emit('form.submitted', {
+                    workspaceId,
+                    formId: form.id,
+                    submissionId: submission.id,
+                });
+                return {
+                    submissionId: submission.id,
+                    formId: form.id,
+                    personId: person.record.id,
+                    companyId: company?.record.id ?? null,
+                    positionId: position?.record.id ?? null,
+                    dealId,
+                    submittedAt: submission.submittedAt,
+                    thankYouMessage: form.thankYouMessage,
+                };
+            });
+        },
+    };
+}
+//# sourceMappingURL=submission.js.map

package/dist/modules/forms/submission.js.map

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

package/dist/modules/forms/tools.d.ts

@@ -0,0 +1,4 @@
+import type { McpToolRegistry } from '../../runtime/module.ts';
+import type { FormsService } from './service.ts';
+export declare function registerFormsTools(mcp: McpToolRegistry, service: FormsService): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/modules/forms/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/modules/forms/tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAW9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAuBhD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CA6BpF"}

package/dist/modules/forms/tools.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { idArg, listWindowShape, pageResult, registerCrudTools, termArg, toListQuery } from '../crudTools.js';
+import { createBody, formResponse, formSubmissionResponse, toCreateInput, toUpdateInput, updateBody, } from './routes.js';
+import { FORM_STATUSES } from './schema.js';
+/**
+ * `forms_*` and `form_submissions_list`, mirroring form management as `forms.md`
+ * scopes it.
+ *
+ * No submit tool and no embed tool. Public submit is HTTP-only for browser
+ * embeds, and an agent that wants to record an inbound contact creates the Person
+ * with the ordinary CRM tools. The embed snippet is built from the origin the
+ * request arrived on, which a tool call does not have.
+ */
+const listArgs = z.strictObject({
+    ...listWindowShape,
+    q: termArg,
+    status: z.enum(FORM_STATUSES).optional().describe('active or paused.'),
+});
+const submissionListArgs = z.strictObject({
+    ...listWindowShape,
+    form_id: idArg.describe('The form whose submissions to read.'),
+});
+export function registerFormsTools(mcp, service) {
+    registerCrudTools(mcp, {
+        resource: 'forms',
+        subject: 'form',
+        about: 'An embeddable inbound form. A submission upserts a person, a company and a ' +
+            'position, and optionally opens a deal.',
+        service,
+        render: formResponse,
+        listArgs,
+        toFilters: (args) => ({ term: args.q, status: args.status }),
+        createArgs: createBody,
+        toCreateInput,
+        updateArgs: updateBody.extend({ id: idArg }),
+        toUpdateInput,
+    });
+    mcp.tool({
+        name: 'form_submissions_list',
+        description: 'List what people submitted through one form, newest first. Cursor paged. ' +
+            'Mirrors GET /v1/forms/{id}/submissions.',
+        inputSchema: submissionListArgs,
+        invoke: async (args, actor) => pageResult(await service.listSubmissions(actor, args.form_id, toListQuery(args)), formSubmissionResponse),
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/modules/forms/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/modules/forms/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,iBAAiB,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7G,OAAO,EACL,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,UAAU,GACX,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG3C;;;;;;;;GAQG;AAEH,MAAM,QAAQ,GAAG,CAAC,CAAC,YAAY,CAAC;IAC9B,GAAG,eAAe;IAClB,CAAC,EAAE,OAAO;IACV,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;CACvE,CAAC,CAAA;AAEF,MAAM,kBAAkB,GAAG,CAAC,CAAC,YAAY,CAAC;IACxC,GAAG,eAAe;IAClB,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,qCAAqC,CAAC;CAC/D,CAAC,CAAA;AAEF,MAAM,UAAU,kBAAkB,CAAC,GAAoB,EAAE,OAAqB;IAC5E,iBAAiB,CAAC,GAAG,EAAE;QACrB,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,MAAM;QACf,KAAK,EACH,6EAA6E;YAC7E,wCAAwC;QAC1C,OAAO;QACP,MAAM,EAAE,YAAY;QACpB,QAAQ;QACR,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5D,UAAU,EAAE,UAAU;QACtB,aAAa;QACb,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;QAC5C,aAAa;KACd,CAAC,CAAA;IAEF,GAAG,CAAC,IAAI,CAAC;QACP,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EACT,2EAA2E;YAC3E,yCAAyC;QAC3C,WAAW,EAAE,kBAAkB;QAC/B,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAC5B,UAAU,CACR,MAAM,OAAO,CAAC,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC,EACrE,sBAAsB,CACvB;KACJ,CAAC,CAAA;AACJ,CAAC"}

package/dist/modules/handbook/index.d.ts

@@ -0,0 +1,15 @@
+import type { KelpieModule } from '../../runtime/module.ts';
+/**
+ * The handbook: the workspace's own narrative, as nested markdown pages.
+ *
+ * Requires only `workspace`. A page attaches to nothing and nothing attaches to
+ * a page: `RECORD_TARGET_TYPES` does not carry `handbook_page`, so there are no
+ * notes, decisions, or timeline entries to keep in step, and no activity
+ * recorder to take as a dependency.
+ *
+ * The starter pages a new workspace opens with are seeded by the workspace
+ * module, in the same transaction that creates the workspace. They are rows a
+ * team then edits, not fixtures this module owns.
+ */
+export declare function createHandbookModule(migrationsDirectory: string): KelpieModule;
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/handbook/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/handbook/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAM3D;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,mBAAmB,EAAE,MAAM,GAAG,YAAY,CAwB9E"}

package/dist/modules/handbook/index.js

@@ -0,0 +1,37 @@
+import { mountHandbookRoutes } from './routes.js';
+import * as schema from './schema.js';
+import { createHandbookService } from './service.js';
+import { registerHandbookTools } from './tools.js';
+/**
+ * The handbook: the workspace's own narrative, as nested markdown pages.
+ *
+ * Requires only `workspace`. A page attaches to nothing and nothing attaches to
+ * a page: `RECORD_TARGET_TYPES` does not carry `handbook_page`, so there are no
+ * notes, decisions, or timeline entries to keep in step, and no activity
+ * recorder to take as a dependency.
+ *
+ * The starter pages a new workspace opens with are seeded by the workspace
+ * module, in the same transaction that creates the workspace. They are rows a
+ * team then edits, not fixtures this module owns.
+ */
+export function createHandbookModule(migrationsDirectory) {
+    return {
+        id: 'handbook',
+        requires: ['workspace'],
+        register(context) {
+            const service = createHandbookService({
+                db: context.db,
+                transaction: context.transaction,
+                createId: context.createId,
+                now: context.now,
+            });
+            context.schema(schema, migrationsDirectory);
+            context.routes((router) => {
+                mountHandbookRoutes(router, { db: context.db, now: context.now, service });
+            });
+            registerHandbookTools(context.mcp, service);
+            return Promise.resolve();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/modules/handbook/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/handbook/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAElD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,mBAA2B;IAC9D,OAAO;QACL,EAAE,EAAE,UAAU;QACd,QAAQ,EAAE,CAAC,WAAW,CAAC;QAEvB,QAAQ,CAAC,OAAO;YACd,MAAM,OAAO,GAAG,qBAAqB,CAAC;gBACpC,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,GAAG,EAAE,OAAO,CAAC,GAAG;aACjB,CAAC,CAAA;YAEF,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;YAE3C,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;gBACxB,mBAAmB,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAA;YAC5E,CAAC,CAAC,CAAA;YAEF,qBAAqB,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;YAE3C,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QAC1B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/modules/handbook/repository.d.ts

@@ -0,0 +1,52 @@
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts';
+import type { Queryable } from '../../runtime/transaction.ts';
+import { handbookPages } from './schema.ts';
+export type HandbookPageRecord = typeof handbookPages.$inferSelect;
+/** The writable column shape. The service builds these; nothing else knows the column names. */
+export type HandbookPageColumns = typeof handbookPages.$inferInsert;
+/**
+ * `sort_order` is not here, and cannot be: it orders a page among its siblings
+ * only, so two pages under different parents share positions and a workspace-wide
+ * sort by it would interleave the levels into nonsense. The tree is rebuilt by
+ * the caller from `parent_id` and `sort_order`, which is what the mockup's
+ * `flattenTree` does.
+ */
+export declare const HANDBOOK_PAGE_SORTS: SortableFields<HandbookPageRecord>;
+/**
+ * Alphabetical, not `-created_at` like the CRM resources.
+ *
+ * A handbook is read, not triaged. Newest-first would open on Agent FAQ and bury
+ * About us, and the creation order of the starter pages is an implementation
+ * detail of the seed rather than anything a reader asked for.
+ */
+export declare const DEFAULT_HANDBOOK_PAGE_SORT = "title";
+export interface HandbookPageFilters {
+    /** `?q=`: title and body. A handbook is searched for what it says, not only for what it is called. */
+    readonly term?: string | undefined;
+    /** `?slug=`, repeatable: the stable handle agent tasks name pages by (`agent-tasks.md`). */
+    readonly slugs?: readonly string[] | undefined;
+}
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export declare function listPages(db: Queryable, workspaceId: string, filters: HandbookPageFilters, window: ListWindow<HandbookPageRecord>): Promise<HandbookPageRecord[]>;
+export declare function findPage(db: Queryable, workspaceId: string, id: string): Promise<HandbookPageRecord | undefined>;
+/**
+ * Every page in the workspace, in sibling order.
+ *
+ * The tree rules (depth, no-descendant-cycles, sibling renumbering) all need the
+ * whole tree, and a workspace handbook is small enough to walk in memory. Reading
+ * it once beats one query per level, and inside a transaction it is the snapshot
+ * every check in that transaction agrees on.
+ */
+export declare function listAllPages(db: Queryable, workspaceId: string): Promise<HandbookPageRecord[]>;
+/** One parent's children, in board order. Used to renumber a sibling set after a move or a delete. */
+export declare function listChildren(db: Queryable, workspaceId: string, parentId: string | null): Promise<HandbookPageRecord[]>;
+/** The slugs already taken in this workspace, for deriving a unique one from a title. */
+export declare function listSlugs(db: Queryable, workspaceId: string): Promise<ReadonlySet<string>>;
+export declare function insertPage(db: Queryable, values: HandbookPageColumns): Promise<HandbookPageRecord>;
+export declare function updatePage(db: Queryable, workspaceId: string, id: string, changes: Partial<HandbookPageColumns>): Promise<HandbookPageRecord | undefined>;
+/**
+ * Deletes one page. The self-referencing foreign key is `on delete cascade`, so
+ * the subtree goes with it without this function naming a single descendant.
+ */
+export declare function deletePage(db: Queryable, workspaceId: string, id: string): Promise<number>;
+//# sourceMappingURL=repository.d.ts.map

package/dist/modules/handbook/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../../src/modules/handbook/repository.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C,MAAM,MAAM,kBAAkB,GAAG,OAAO,aAAa,CAAC,YAAY,CAAA;AAElE,gGAAgG;AAChG,MAAM,MAAM,mBAAmB,GAAG,OAAO,aAAa,CAAC,YAAY,CAAA;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,cAAc,CAAC,kBAAkB,CAIlE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,UAAU,CAAA;AAEjD,MAAM,WAAW,mBAAmB;IAClC,sGAAsG;IACtG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;CAC/C;AAcD,mHAAmH;AACnH,wBAAgB,SAAS,CACvB,EAAE,EAAE,SAAS,EACb,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,UAAU,CAAC,kBAAkB,CAAC,GACrC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAS/B;AAED,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,SAAS,EACb,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAQzC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,SAAS,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAM/B;AAED,sGAAsG;AACtG,wBAAgB,YAAY,CAC1B,EAAE,EAAE,SAAS,EACb,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAW/B;AAED,yFAAyF;AACzF,wBAAsB,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAOhG;AAED,wBAAsB,UAAU,CAC9B,EAAE,EAAE,SAAS,EACb,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAED,wBAAsB,UAAU,CAC9B,EAAE,EAAE,SAAS,EACb,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACpC,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAQzC;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOhG"}

package/dist/modules/handbook/repository.js

@@ -0,0 +1,109 @@
+import { and, asc, eq, ilike, inArray, isNull, or } from 'drizzle-orm';
+import { keysetCondition, orderByWindow, textSort, timestampSort } from '../../lib/pagination.js';
+import { containsPattern } from '../../lib/search.js';
+import { handbookPages } from './schema.js';
+/**
+ * `sort_order` is not here, and cannot be: it orders a page among its siblings
+ * only, so two pages under different parents share positions and a workspace-wide
+ * sort by it would interleave the levels into nonsense. The tree is rebuilt by
+ * the caller from `parent_id` and `sort_order`, which is what the mockup's
+ * `flattenTree` does.
+ */
+export const HANDBOOK_PAGE_SORTS = {
+    title: textSort(handbookPages.title, (page) => page.title),
+    created_at: timestampSort(handbookPages.createdAt, (page) => page.createdAt),
+    updated_at: timestampSort(handbookPages.updatedAt, (page) => page.updatedAt),
+};
+/**
+ * Alphabetical, not `-created_at` like the CRM resources.
+ *
+ * A handbook is read, not triaged. Newest-first would open on Agent FAQ and bury
+ * About us, and the creation order of the starter pages is an implementation
+ * detail of the seed rather than anything a reader asked for.
+ */
+export const DEFAULT_HANDBOOK_PAGE_SORT = 'title';
+function conditionsFor(workspaceId, filters) {
+    const pattern = filters.term === undefined ? undefined : containsPattern(filters.term);
+    return [
+        eq(handbookPages.workspaceId, workspaceId),
+        pattern === undefined
+            ? undefined
+            : or(ilike(handbookPages.title, pattern), ilike(handbookPages.body, pattern)),
+        filters.slugs === undefined ? undefined : inArray(handbookPages.slug, filters.slugs),
+    ];
+}
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export function listPages(db, workspaceId, filters, window) {
+    return db
+        .select()
+        .from(handbookPages)
+        .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, handbookPages.id)))
+        .orderBy(...orderByWindow(window, handbookPages.id))
+        .limit(window.fetchLimit);
+}
+export async function findPage(db, workspaceId, id) {
+    const [found] = await db
+        .select()
+        .from(handbookPages)
+        .where(and(eq(handbookPages.workspaceId, workspaceId), eq(handbookPages.id, id)))
+        .limit(1);
+    return found;
+}
+/**
+ * Every page in the workspace, in sibling order.
+ *
+ * The tree rules (depth, no-descendant-cycles, sibling renumbering) all need the
+ * whole tree, and a workspace handbook is small enough to walk in memory. Reading
+ * it once beats one query per level, and inside a transaction it is the snapshot
+ * every check in that transaction agrees on.
+ */
+export function listAllPages(db, workspaceId) {
+    return db
+        .select()
+        .from(handbookPages)
+        .where(eq(handbookPages.workspaceId, workspaceId))
+        .orderBy(asc(handbookPages.sortOrder), asc(handbookPages.id));
+}
+/** One parent's children, in board order. Used to renumber a sibling set after a move or a delete. */
+export function listChildren(db, workspaceId, parentId) {
+    return db
+        .select()
+        .from(handbookPages)
+        .where(and(eq(handbookPages.workspaceId, workspaceId), parentId === null ? isNull(handbookPages.parentId) : eq(handbookPages.parentId, parentId)))
+        .orderBy(asc(handbookPages.sortOrder), asc(handbookPages.id));
+}
+/** The slugs already taken in this workspace, for deriving a unique one from a title. */
+export async function listSlugs(db, workspaceId) {
+    const rows = await db
+        .select({ slug: handbookPages.slug })
+        .from(handbookPages)
+        .where(eq(handbookPages.workspaceId, workspaceId));
+    return new Set(rows.map((row) => row.slug));
+}
+export async function insertPage(db, values) {
+    const [created] = await db.insert(handbookPages).values(values).returning();
+    if (created === undefined) {
+        throw new Error(`Inserting handbook page ${values.id} returned no row`);
+    }
+    return created;
+}
+export async function updatePage(db, workspaceId, id, changes) {
+    const [updated] = await db
+        .update(handbookPages)
+        .set(changes)
+        .where(and(eq(handbookPages.workspaceId, workspaceId), eq(handbookPages.id, id)))
+        .returning();
+    return updated;
+}
+/**
+ * Deletes one page. The self-referencing foreign key is `on delete cascade`, so
+ * the subtree goes with it without this function naming a single descendant.
+ */
+export async function deletePage(db, workspaceId, id) {
+    const deleted = await db
+        .delete(handbookPages)
+        .where(and(eq(handbookPages.workspaceId, workspaceId), eq(handbookPages.id, id)))
+        .returning({ id: handbookPages.id });
+    return deleted.length;
+}
+//# sourceMappingURL=repository.js.map