@odla-ai/chapter 0.15.0 → 0.16.0

package/README.md

@@ -235,22 +235,37 @@ These bite silently — a smoke test won't catch them:
 - **`--legacy-peer-deps` is a diagnostic, not a setting.** It suppresses exactly
   the peer conflict that tells you a pair is unsupported. If you need it, find out
   why first.
-- **The admin surface is intentionally minimal, and staying that way.** chapter
-  ships `/api/admin/scheduling` (booking rules, with field-keyed validation
-  messages) and `/api/admin/meetings` (the reconciled agenda, with the applicant
-  joined, `?all=1`, `from`/`to`, drift fields, Meet/Calendar links and the group
-  timezone), plus `peopleSection`. **Dashboard, billing, email config/log/test,
-  per-person comms, people list, role changes, approve and refund are out of
-  scope** — they are yours as host routes via the seam. Don't plan around them
-  shipping.
-- **`onboardingInvite` is a template with no built-in caller.** It is seeded into
-  the group's email settings (so you can edit its copy) but chapter never fires
-  it, because the moment it would fire — approval — is a host route (approval is
-  out of scope, above). Send it from your own approve handler via `sendTemplated`;
-  the seed existing does not mean the built-ins send it.
-- **Server-side Clerk is exported, even though the admin *routes* aren't.** A role
-  change is your host route — but you don't hand-roll the Clerk REST calls for it.
-  Beside `createClerkUser`/`createClerkInvitation`/`canChangeRole`, chapter exports
+- **The admin operational surface ships (0.16.0).** `/api/admin/*` is now a full
+  membership-operations API, admin-gated (`verifyUser` + `isAdmin`):
+  - **Roster/identity:** `GET /people` (union of `$users` + applications by email,
+    roles from `clerkListUsers`), `GET /people/access`, `POST /people/role`,
+    `POST /crm/sync` (backfill/reproject).
+  - **Pipeline/meetings:** `GET /dashboard` (flow counts, stage counts + weekly
+    delta, agenda, live revenue), `GET /meetings` (reconciled agenda),
+    `GET/PUT /scheduling`, `POST /meetings/:id/{reschedule,cancel}`,
+    `PATCH /applications/:id`.
+  - **Money:** `GET /billing` (applications ⋈ live Stripe subs; `truncated` flags a
+    >100 page instead of losing rows; `billingReady:false` when no Stripe key is
+    vaulted), `POST /applications/:id/{approve,refund}`.
+  - **Email:** `GET/PUT /group/email`, `GET /email/log`, `POST /email/test`,
+    `GET /people/:id/comms` (sent mail + reconstructed calendar invitations).
+
+  Two behaviours are **config, not code** — the mechanics are chapter's, the
+  decisions are yours (same model as `sends`):
+
+  ```ts
+  defineChapter({ operations: {
+    onApprove: { promoteTo: "member", send: "onboardingInvite" }, // promoteTo defaults to the rung below admin; either can be false
+    refund:    { allowedFrom: ["paid_pending_vetting"], cancelSubscription: true }, // allowedFrom validated against the pipeline
+  }});
+  ```
+
+  The escalation rules (super-admin tier, self-demotion lockout) are **not** seams
+  — `canChangeRole` package-enforces them so a site can't weaken them. `approve`
+  is the caller `onboardingInvite` was missing.
+- **The server-side Clerk primitives are exported too** — for host routes beyond
+  the built-in `/people/role`. Beside
+  `createClerkUser`/`createClerkInvitation`/`canChangeRole`, chapter exports
   the odla→Clerk write half: `clerkGetUserByEmail`, `clerkGetUser`, `clerkListUsers`
   (auto-paginated — never a silent 100-user cap), and `clerkSetRole`. Two
   load-bearing semantics: an absent `public_metadata.role` reads as the lowest rung

package/dist/index.cjs

@@ -24,8 +24,10 @@ __export(index_exports, {
   applicantProfile: () => applicantProfile,
   applicationBookingUpdate: () => applicationBookingUpdate,
   applicationSummary: () => applicationSummary,
+  backfillCrm: () => backfillCrm,
   bookingDecision: () => bookingDecision,
   brandTokens: () => brandTokens,
+  bucketSeries: () => bucketSeries,
   buildGroupSeed: () => buildGroupSeed,
   canApprove: () => canApprove,
   canBook: () => canBook,
@@ -65,6 +67,7 @@ __export(index_exports, {
   memberSession: () => memberSession,
   normalizeWebhookEvent: () => normalizeWebhookEvent,
   paymentsReady: () => paymentsReady,
+  personInputFromApp: () => personInputFromApp,
   planDelivery: () => planDelivery,
   projectApplicant: () => projectApplicant,
   projectSharedRecord: () => projectSharedRecord,
@@ -83,9 +86,12 @@ __export(index_exports, {
   sharedPersonInput: () => sharedPersonInput,
   slotWindow: () => slotWindow,
   stageIndex: () => stageIndex,
+  stripeCall: () => stripeCall,
   stripeForm: () => stripeForm,
+  subAnnualCents: () => subAnnualCents,
   submitApplication: () => submitApplication,
   subscriptionIdempotencyKey: () => subscriptionIdempotencyKey,
+  syncApplicationToCrm: () => syncApplicationToCrm,
   validateScheduling: () => validateScheduling,
   verifyStripeSignature: () => verifyStripeSignature,
   webhookMutationId: () => webhookMutationId
@@ -631,6 +637,27 @@ function defineChapter(config) {
     );
   }
   const sends = { adminNotification };
+  const onApproveCfg = config.operations?.onApprove ?? {};
+  const belowAdmin = auth.ladder[auth.ladder.length - 2] ?? auth.adminRole;
+  const promoteTo = onApproveCfg.promoteTo === void 0 ? belowAdmin : onApproveCfg.promoteTo;
+  if (promoteTo !== false && !auth.ladder.includes(promoteTo)) {
+    throw new Error(
+      `defineChapter.operations.onApprove.promoteTo: "${String(promoteTo)}" is not in the auth ladder (${auth.ladder.join(", ")})`
+    );
+  }
+  const refundCfg = config.operations?.refund ?? {};
+  if (refundCfg.allowedFrom !== void 0) {
+    const unknown = refundCfg.allowedFrom.filter((s) => !pipeline.stages.includes(s));
+    if (unknown.length > 0) {
+      throw new Error(
+        `defineChapter.operations.refund.allowedFrom: ${unknown.map((s) => `"${s}"`).join(", ")} not in the pipeline (${pipeline.stages.join(", ")})`
+      );
+    }
+  }
+  const operations = {
+    onApprove: { promoteTo, send: onApproveCfg.send === void 0 ? "onboardingInvite" : onApproveCfg.send },
+    refund: { allowedFrom: refundCfg.allowedFrom ?? null, cancelSubscription: refundCfg.cancelSubscription ?? true }
+  };
   const chapter = {
     config,
     id: id2,
@@ -645,6 +672,7 @@ function defineChapter(config) {
     services,
     account,
     sends,
+    operations,
     groupSeed: () => mode === "chapter" ? buildGroupSeed(config) : null
   };
   if (config.url !== void 0) chapter.url = config.url;
@@ -771,16 +799,16 @@ async function sendTemplated(deps, input) {
   return error ? { sent: false, reason: error } : { sent: true };
 }
 function emailGroupFrom(row) {
-  const str = (v) => typeof v === "string" ? v : void 0;
+  const str2 = (v) => typeof v === "string" ? v : void 0;
   const templates = row.emailTemplates && typeof row.emailTemplates === "object" ? row.emailTemplates : {};
   return {
     id: String(row.id),
     name: String(row.name ?? ""),
-    replyTo: str(row.replyTo) ?? "",
-    debugEmail: str(row.debugEmail),
-    refundPolicyText: str(row.refundPolicyText),
-    commitmentText: str(row.commitmentText),
-    normsText: str(row.normsText),
+    replyTo: str2(row.replyTo) ?? "",
+    debugEmail: str2(row.debugEmail),
+    refundPolicyText: str2(row.refundPolicyText),
+    commitmentText: str2(row.commitmentText),
+    normsText: str2(row.normsText),
     emailTemplates: templates
   };
 }
@@ -928,6 +956,126 @@ async function projectApplicant(deps, applicant) {
   }
 }
 
+// src/crm-sync.ts
+var import_crm4 = require("@odla-ai/crm");
+var str = (v) => typeof v === "string" ? v : v == null ? "" : String(v);
+function personInputFromApp(chapter, app) {
+  const input = sharedPersonInput({
+    email: str(app.email),
+    firstName: str(app.firstName) || void 0,
+    lastName: str(app.lastName) || void 0,
+    phone: str(app.phone) || void 0,
+    linkedin: str(app.linkedin) || void 0,
+    hubRecordId: str(app.id)
+  });
+  for (const f of chapter.application.crmFields) {
+    if (app[f] !== void 0) input[f] = app[f];
+  }
+  if (app.id !== void 0) input.applicationId = str(app.id);
+  return input;
+}
+function billingColumns(app) {
+  const status = str(app.status);
+  const paid = Boolean(app.stripeSubscriptionId) && status !== "refunded";
+  const billingStatus = status === "refunded" ? "refunded" : app.canceled === true ? "canceled" : paid ? "active" : "none";
+  const cols = { billingStatus };
+  if (app.stripeCustomerId) cols.stripeCustomerId = str(app.stripeCustomerId);
+  if (app.stripeSubscriptionId) cols.subscriptionId = str(app.stripeSubscriptionId);
+  if (typeof app.renewalAt === "number") cols.renewalAt = app.renewalAt;
+  return cols;
+}
+async function syncApplicationToCrm(deps, opts) {
+  const emailKey = str(opts.app.email).toLowerCase();
+  if (!emailKey) return null;
+  const crmDeps = { crm: deps.crm, db: deps.db, now: deps.now, newId: deps.newId };
+  const input = personInputFromApp(deps.chapter, opts.app);
+  const { crm_record } = await deps.db.query({
+    crm_record: { $: { where: { type: "person", primaryEmail: emailKey }, limit: 1 } }
+  });
+  const existing = crm_record?.[0] ?? null;
+  const stage = opts.stage || void 0;
+  let recordId;
+  if (existing && typeof existing.id === "string") {
+    recordId = existing.id;
+    await (0, import_crm4.updateRecord)(crmDeps, { id: recordId, input });
+  } else {
+    const created = await (0, import_crm4.createRecord)(crmDeps, { type: "person", input, ...stage ? { stage } : {} });
+    recordId = created.id;
+  }
+  if (existing && stage && existing.stage !== stage) {
+    await (0, import_crm4.setStage)(crmDeps, { id: recordId, to: stage, authorId: "system", mutationId: `crm:stage:${recordId}:${stage}` }).catch(() => void 0);
+  }
+  await deps.db.transact([{ t: "update", ns: "crm_record", id: recordId, attrs: billingColumns(opts.app) }]);
+  await (0, import_crm4.linkIdentity)(crmDeps, { recordId, email: emailKey, mutationId: `crm:link:${recordId}:${emailKey}` }).catch(() => void 0);
+  return recordId;
+}
+async function backfillCrm(deps) {
+  const [appsRes, usersRes] = await Promise.all([
+    deps.db.query({ applications: { $: { order: { createdAt: "desc" }, limit: 1e3 } } }),
+    deps.db.query({ $users: { $: { limit: 1e3 } } })
+  ]);
+  const seen = /* @__PURE__ */ new Set();
+  let synced = 0;
+  const errors = [];
+  const run = async (app, stage) => {
+    const key = str(app.email).toLowerCase();
+    if (!key || seen.has(key)) return;
+    seen.add(key);
+    try {
+      await syncApplicationToCrm(deps, { app, stage });
+      synced += 1;
+    } catch (err) {
+      errors.push({ email: key, error: err instanceof Error ? err.message : String(err) });
+    }
+  };
+  for (const a of appsRes.applications ?? []) await run(a, str(a.status));
+  for (const u of usersRes.$users ?? []) {
+    if (u.deleted === true) continue;
+    await run({ email: u.email, firstName: str(u.name) });
+  }
+  return { synced, errors };
+}
+
+// src/series.ts
+function bucketSeries(points, now, weeks = 12) {
+  const WEEK = 7 * 864e5;
+  const end = now;
+  const start = end - weeks * WEEK;
+  const buckets = Array.from({ length: weeks }, (_, i) => ({ weekStart: start + i * WEEK, value: 0 }));
+  for (const p of points) {
+    if (!Number.isFinite(p.t) || p.t < start || p.t > end) continue;
+    const idx = Math.min(weeks - 1, Math.floor((p.t - start) / WEEK));
+    const bucket = buckets[idx];
+    if (bucket) bucket.value += Number.isFinite(p.v) ? p.v : 0;
+  }
+  return buckets;
+}
+function subAnnualCents(sub) {
+  const items = sub.items?.data ?? [];
+  let cents = 0;
+  for (const it of items) {
+    const price = it.price ?? {};
+    const per = (price.unit_amount ?? 0) * (it.quantity ?? 1);
+    cents += price.recurring?.interval === "month" ? per * 12 : per;
+  }
+  return cents;
+}
+
+// src/payments-stripe.ts
+async function stripeCall(sk, method, path, params, idempotencyKey) {
+  const qs = method === "GET" && params ? `?${stripeForm(params)}` : "";
+  const headers = { authorization: `Bearer ${sk}` };
+  if (idempotencyKey) headers["idempotency-key"] = idempotencyKey;
+  const init = { method, headers };
+  if (method === "POST" && params) {
+    headers["content-type"] = "application/x-www-form-urlencoded";
+    init.body = stripeForm(params);
+  }
+  const res = await fetch(`https://api.stripe.com${path}${qs}`, init);
+  const body = await res.json().catch(() => ({}));
+  return { ok: res.ok, status: res.status, body };
+}
+
 // src/clerk.ts
 var heal = (status) => status === 422 ? { ok: true, status, existed: true } : { ok: false, status };
 function clerkInviteRequest(input) {