create-ailk 0.20.0 → 0.22.0

package/templates/apps/web/app/[locale]/careers/[slug]/apply.actions.ts

@@ -0,0 +1,293 @@
+"use server";
+
+/**
+ * captureLeadAction — the job page's apply form (#8746 D4, D5). Paired, like
+ * /contact's action of the same name, with the `ailkCaptureLead` MCP tool: an
+ * application is a lead written to `POST /v1/leads/submit`, so an agent
+ * applies through the same capture route. A distinct `*Action` name would
+ * claim a capability with no MCP twin (`apps/mcp/__tests__/parity.test.ts`).
+ *
+ * The page binds the posting's slug as the first argument
+ * (`captureLeadAction.bind(null, slug)`); it travels as the lead's hidden
+ * `job` value and must be a slug. Bound arguments round-trip through the
+ * browser, so it is attribution, never authorization.
+ *
+ * The lead (#8746 AC-5): source `flow:job-application` — always, so it is an
+ * Inbox submission of the Job application magnet (a post from the built-in
+ * form too: the magnet is seeded into every workspace and never deleted) —
+ * the applicant's email, and a payload of `name` (first + last),
+ * `first_name`, `last_name`, the optional `phone` and `linkedin_url`, any
+ * extra field the owner added to the magnet (bounded as /contact bounds
+ * them), and `job`. `name`, `job` and the read fields are spread after the
+ * extras, so no form field overrides them. The write goes through the site's
+ * lead writer (`src/lib/lead-write.ts`), which adds `payload.site` and
+ * `payload.page` ("careers") and sends no `siteId`.
+ *
+ * Checks, before any write: the honeypot (a filled one answers success and
+ * sends nothing); first name, last name and email required; a LinkedIn URL,
+ * when given, an http(s) URL — a bare domain gains `https://`, the flow
+ * engine's `url` idiom; the terms box ticked, as the form block requires; and
+ * the per-visitor limit /contact runs, in /contact's own bucket so a visitor's
+ * lead posts stay at 30 per 10 minutes however they are split (skipped when
+ * no client address is readable). Outcomes map as /contact's do: the API's
+ * `lead_capture_not_configured` or an unreachable API is `unavailable`, any
+ * other refusal the generic error.
+ */
+
+import { visitorForwardHeaders } from "@working-theory/api-client";
+import {
+  LEAD_CAPTURE_HONEYPOT,
+  type LeadCaptureFormState,
+} from "@working-theory/ui";
+import {
+  accountEmailHintSchema,
+  flowLeadSource,
+  JOB_APPLICATION_FLOW_SLUG,
+  leadSubmitNextSchema,
+} from "@working-theory/validation";
+import { cookies, headers } from "next/headers";
+import { getLocale, getTranslations } from "next-intl/server";
+import { z } from "zod";
+
+import { accountInviteHref } from "../../../../lib/account-invite";
+import {
+  consentVisitorHeader,
+  readConsentVisitor,
+} from "../../../../lib/consent-visitor";
+import { writeLead } from "../../../../src/lib/lead-write";
+import {
+  checkRateLimit,
+  clientIpFromHeaders,
+} from "../../../../src/lib/rate-limit";
+
+const GENERIC_ERROR = "Something went wrong, please try again.";
+const RATE_LIMITED =
+  "Too many applications from here. Please try again in a few minutes.";
+const CONSENT_REQUIRED = "Please accept the terms to send your application.";
+
+const RATE_LIMIT_MAX_CALLS = 30;
+const RATE_LIMIT_WINDOW_MS = 10 * 60 * 1000;
+
+const SOURCE = flowLeadSource(JOB_APPLICATION_FLOW_SLUG);
+const JOB_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,127}$/;
+const HAS_SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/** Field names the action reads itself, or writes — never copied from the form. */
+const RESERVED_FIELDS = new Set([
+  "first_name",
+  "last_name",
+  "email",
+  "phone",
+  "linkedin_url",
+  "consent",
+  "name",
+  "job",
+  "source",
+  LEAD_CAPTURE_HONEYPOT,
+]);
+const MAX_EXTRA_FIELDS = 20;
+const MAX_EXTRA_FIELD_LENGTH = 2000;
+
+const optionalText = (max: number) =>
+  z.preprocess(
+    (v) => (typeof v === "string" && v.trim() !== "" ? v.trim() : undefined),
+    z.string().max(max).optional(),
+  );
+
+/** A LinkedIn URL: blank is absent; a bare domain gains `https://`; only http(s). */
+const linkedinUrl = z.preprocess(
+  (v) => {
+    if (typeof v !== "string" || v.trim() === "") return undefined;
+    const value = v.trim();
+    return HAS_SCHEME_RE.test(value) ? value : `https://${value}`;
+  },
+  z
+    .string()
+    .max(2000)
+    .refine((value) => {
+      try {
+        const url = new URL(value);
+        return (
+          (url.protocol === "https:" || url.protocol === "http:") &&
+          url.hostname.includes(".") &&
+          // No credentials: `https://linkedin.com@evil.example/` would show
+          // the operator a LinkedIn-looking link to another host.
+          url.username === "" &&
+          url.password === ""
+        );
+      } catch {
+        return false;
+      }
+    }, "Enter a valid URL.")
+    .optional(),
+);
+
+const applicationSchema = z.object({
+  first_name: z.string().trim().min(1, "Enter your first name.").max(100),
+  last_name: z.string().trim().min(1, "Enter your last name.").max(100),
+  email: z.string().trim().email("Enter a valid email address.").max(254),
+  phone: optionalText(32),
+  linkedin_url: linkedinUrl,
+});
+
+/** The extra fields, or `null` over the bounds. Files and `$ACTION_…` keys are skipped. */
+function extraFields(formData: FormData): Record<string, string> | null {
+  const extra: Record<string, string> = {};
+  let count = 0;
+  for (const [key, value] of formData.entries()) {
+    if (RESERVED_FIELDS.has(key) || key.startsWith("$ACTION")) continue;
+    if (typeof value !== "string") continue;
+    if (value.length > MAX_EXTRA_FIELD_LENGTH) return null;
+    if (!Object.hasOwn(extra, key)) count += 1;
+    if (count > MAX_EXTRA_FIELDS) return null;
+    extra[key] = value;
+  }
+  return extra;
+}
+
+function isNotConfigured(res: { status: number; body: unknown }): boolean {
+  return (
+    res.status === 503 &&
+    typeof res.body === "object" &&
+    res.body !== null &&
+    (res.body as { error?: unknown }).error === "lead_capture_not_configured"
+  );
+}
+
+function isApiUnreachable(res: { status: number }): boolean {
+  return res.status === 0 || res.status === 502 || res.status === 504;
+}
+
+const field = (formData: FormData, name: string): unknown =>
+  formData.get(name) ?? undefined;
+
+/**
+ * #8771 D7 — the thank-you's "Track this in your account" link, when the API
+ * answered `next: { completion: "invite" }` and this site can build one; else
+ * exactly `{ kind: "success" }`. The application is already written, so a
+ * refusal or a throw anywhere here is still a success — an error would invite
+ * a duplicate application.
+ */
+async function successState(
+  next: unknown,
+  email: string,
+): Promise<LeadCaptureFormState> {
+  try {
+    const parsed = leadSubmitNextSchema.safeParse(next);
+    if (!parsed.success || parsed.data.completion !== "invite") {
+      return { kind: "success" };
+    }
+    const hint = accountEmailHintSchema.safeParse(email);
+    if (!hint.success) return { kind: "success" };
+    const locale = await getLocale();
+    const href = accountInviteHref(locale, hint.data);
+    if (href === null) return { kind: "success" };
+    const t = await getTranslations({ locale, namespace: "contact" });
+    return { kind: "success", next: { href, label: t("trackInAccount") } };
+  } catch {
+    return { kind: "success" };
+  }
+}
+
+export async function captureLeadAction(
+  job: string,
+  _prevState: LeadCaptureFormState,
+  formData: FormData,
+): Promise<LeadCaptureFormState> {
+  const honeypot = formData.get(LEAD_CAPTURE_HONEYPOT);
+  if (typeof honeypot === "string" && honeypot !== "")
+    return { kind: "success" };
+
+  // A bound argument comes back from the browser: check its type, not only its text.
+  if (typeof job !== "string" || !JOB_SLUG_RE.test(job)) {
+    return { kind: "error", message: GENERIC_ERROR };
+  }
+
+  const fieldErrors: Record<string, string> = {};
+  if (formData.get("consent") !== "true")
+    fieldErrors.consent = CONSENT_REQUIRED;
+
+  const parsed = applicationSchema.safeParse({
+    first_name: field(formData, "first_name") ?? "",
+    last_name: field(formData, "last_name") ?? "",
+    email: field(formData, "email") ?? "",
+    phone: field(formData, "phone"),
+    linkedin_url: field(formData, "linkedin_url"),
+  });
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      const name = String(issue.path[0] ?? "form");
+      fieldErrors[name] ??= issue.message;
+    }
+  }
+  if (!parsed.success || Object.keys(fieldErrors).length > 0) {
+    return { kind: "error", fieldErrors };
+  }
+
+  const extra = extraFields(formData);
+  if (extra === null) return { kind: "error", message: GENERIC_ERROR };
+
+  const { first_name, last_name, email, phone, linkedin_url } = parsed.data;
+  const payload = {
+    ...extra,
+    name: `${first_name} ${last_name}`,
+    first_name,
+    last_name,
+    ...(phone !== undefined && { phone }),
+    ...(linkedin_url !== undefined && { linkedin_url }),
+    job,
+  };
+
+  let requestHeaders: Awaited<ReturnType<typeof headers>> | undefined;
+  try {
+    requestHeaders = await headers();
+  } catch {
+    // No request scope — no forwarding, and the visitor is "unknown".
+  }
+
+  const visitor = requestHeaders
+    ? clientIpFromHeaders(requestHeaders)
+    : "unknown";
+  if (
+    visitor !== "unknown" &&
+    !checkRateLimit(
+      `contact:${visitor}`,
+      RATE_LIMIT_MAX_CALLS,
+      RATE_LIMIT_WINDOW_MS,
+    )
+  ) {
+    return { kind: "error", message: RATE_LIMITED };
+  }
+
+  let init: { headers: Record<string, string> } | undefined;
+  if (requestHeaders) {
+    const forwarded = visitorForwardHeaders(
+      requestHeaders,
+      process.env.AILK_VISITOR_FORWARD_KEY,
+    );
+    if (forwarded) init = { headers: forwarded };
+  }
+  try {
+    const visitorId = readConsentVisitor(await cookies());
+    if (visitorId)
+      init = {
+        headers: {
+          ...(init?.headers ?? {}),
+          ...consentVisitorHeader(visitorId),
+        },
+      };
+  } catch {
+    // No request scope — submit with no visitor-link header.
+  }
+
+  const res = await writeLead(
+    { source: SOURCE, email, page: "careers", payload },
+    init,
+  );
+  if (!res.ok) {
+    if (isNotConfigured(res) || isApiUnreachable(res))
+      return { kind: "unavailable" };
+    return { kind: "error", message: GENERIC_ERROR };
+  }
+  return successState(res.body.next, email);
+}

package/templates/apps/web/app/[locale]/careers/[slug]/job-application-form.ts

@@ -0,0 +1,115 @@
+/**
+ * jobApplicationFormFromConfig — the Job application magnet's field step, as
+ * the shared `LeadCaptureForm` block renders it on a job page (#8746 D5).
+ *
+ * Reads the config's first step, which must be a `field` step holding fields
+ * named `first_name`, `last_name` and `email` (what the apply action needs);
+ * anything else answers `null` and the page renders the built-in form, the
+ * seeded config itself (`jobApplicationFormFallback`).
+ *
+ * Each `text`, `email`, `tel`, `url`, `textarea` or `select` field is mapped
+ * in order. First and last name sit side by side, then email and phone; every
+ * other field runs full width. `consent` and `address` fields are not
+ * rendered: the block draws its own terms box, labelled with the step's first
+ * `consent` field's label when it has one (as /contact does). The step's
+ * `copy.title` heads the section and its `copy.cta` is the submit label.
+ *
+ * Copy resolves with the one LocalizedString rule every flow surface shares
+ * (`resolveLocalizedString`). Pure: no fetch, no React.
+ */
+import type { ContactFormField } from "@working-theory/ui";
+import {
+  jobApplicationFlowConfig,
+  resolveLocalizedString,
+  type FlowConfig,
+} from "@working-theory/validation";
+
+export interface JobApplicationFormView {
+  /** The step's `copy.title`. */
+  title: string;
+  fields: ContactFormField[];
+  /** The step's first consent field's label — `[Label](key)` tokens intact. */
+  consentStatement?: string;
+  /** The step's `copy.cta`. */
+  submitLabel?: string;
+}
+
+type FieldStep = Extract<FlowConfig["steps"][number], { type: "field" }>;
+type FieldDef = FieldStep["fields"][number];
+
+const RENDERED_TYPES = [
+  "text",
+  "email",
+  "tel",
+  "url",
+  "textarea",
+  "select",
+] as const;
+type RenderedType = (typeof RENDERED_TYPES)[number];
+
+const REQUIRED_NAMES = ["first_name", "last_name", "email"] as const;
+const PAIRED_NAMES: ReadonlySet<string> = new Set([
+  "first_name",
+  "last_name",
+  "email",
+  "phone",
+]);
+
+function isRendered(type: FieldDef["inputType"]): type is RenderedType {
+  return (RENDERED_TYPES as readonly string[]).includes(type);
+}
+
+export function jobApplicationFormFromConfig(
+  config: FlowConfig,
+  locale: string,
+): JobApplicationFormView | null {
+  const step = config.steps[0];
+  if (step?.type !== "field") return null;
+  const names = new Set(step.fields.map((f) => f.name));
+  if (!REQUIRED_NAMES.every((name) => names.has(name))) return null;
+
+  const resolve = (value: Record<string, string>): string =>
+    resolveLocalizedString(value, locale, config.defaultLocale);
+
+  const fields: ContactFormField[] = [];
+  for (const field of step.fields) {
+    if (!isRendered(field.inputType)) continue;
+    fields.push({
+      name: field.name,
+      type: field.inputType,
+      label: resolve(field.copy.label),
+      required: field.required ?? false,
+      ...(field.copy.placeholder !== undefined && {
+        placeholder: resolve(field.copy.placeholder),
+      }),
+      ...(field.copy.help !== undefined && {
+        helpText: resolve(field.copy.help),
+      }),
+      ...(field.options !== undefined && {
+        options: field.options.map((o) => ({
+          value: o.value,
+          label: resolve(o.label),
+        })),
+      }),
+      colSpan: PAIRED_NAMES.has(field.name) ? 1 : 2,
+    });
+  }
+
+  const consent = step.fields.find((f) => f.inputType === "consent");
+  return {
+    title: resolve(step.copy.title),
+    fields,
+    ...(consent !== undefined && {
+      consentStatement: resolve(consent.copy.label),
+    }),
+    ...(step.copy.cta !== undefined && { submitLabel: resolve(step.copy.cta) }),
+  };
+}
+
+/** The built-in form: the seeded magnet's own config. */
+export function jobApplicationFormFallback(
+  locale: string,
+): JobApplicationFormView {
+  // The seeded config always maps — its test pins first_name, last_name, email.
+  return jobApplicationFormFromConfig(jobApplicationFlowConfig, locale)!;
+}

package/templates/apps/web/app/[locale]/careers/[slug]/page.tsx

@@ -1,16 +1,100 @@
 // JobPosting detail page. Reads the JobPosting MDX for the given slug, renders via
 // next-mdx-remote/rsc, and emits a JSON-LD <script>. Unknown slugs 404 through renderPage.
 // Careers list at /careers links here; each job posting lives at /careers/<slug>.
+//
+// Under the posting, an `#apply` section (#8746 D1, D5) draws the workspace's
+// Job application magnet the way /contact draws its Contact form: the field
+// step of `flows.get("job-application")` (the public flow read — the API
+// resolves the workspace), else the built-in form, which is the seeded config
+// itself, for a magnet that is absent, off (draft), unreadable or unusable. It
+// is the shared `LeadCaptureForm` bound to this page's apply action with the
+// posting's slug as the lead's hidden `job`; a submission is a
+// `flow:job-application` lead. When the API says this deployment accepts no
+// lead, the section shows the site's contact email instead. The form's copy is
+// the `contact` catalog's, but for its success line, the `careers` catalog's
+// `applicationSuccess`. The page is rendered on every request, and its two hub
+// reads (capture status, the magnet) are shared across requests for 15 seconds
+// per server instance, as /contact's are (#8731): a burst of views is one hub
+// read of each, and an Admin edit shows within 15 seconds. An unknown posting
+// 404s before any read.
+import { flows, leads } from "@working-theory/api-client";
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
 import { renderPage, renderPageMetadata } from "@working-theory/page-renderer";
+import {
+  ContactFallback,
+  Container,
+  Heading,
+  LeadCaptureForm,
+  localeHref,
+} from "@working-theory/ui";
+import {
+  JOB_APPLICATION_FLOW_SLUG,
+  type FlowConfig,
+} from "@working-theory/validation";
 import type { Metadata } from "next";
+import { getTranslations } from "next-intl/server";
 import type { ReactElement } from "react";
 
+import { contactFormText } from "../../contact/contact-form-text";
+import { readSiteContactEmail } from "../../contact/site-contact-email";
+
+import { captureLeadAction } from "./apply.actions";
+import {
+  jobApplicationFormFallback,
+  jobApplicationFormFromConfig,
+} from "./job-application-form";
+
+// #8746 D5 — the page is rendered on every request.
+export const dynamic = "force-dynamic";
+
 interface Props {
   params: Promise<{ locale: string; slug: string }>;
   getMdxSource?: typeof defaultGetMdxSource;
 }
 
+/** How long the two hub reads are shared across requests (/contact's #8731 value). */
+const HUB_READ_TTL_MS = 15_000;
+
+const hubReads = new Map<string, { at: number; read: Promise<unknown> }>();
+
+/**
+ * `read()`'s result, shared per instance for HUB_READ_TTL_MS; concurrent calls
+ * share one in-flight read, and a failed read (settled as its fallback) is
+ * shared the same way, so an unreachable hub is not retried per view.
+ */
+function sharedHubRead<T>(key: string, read: () => Promise<T>): Promise<T> {
+  const now = Date.now();
+  const hit = hubReads.get(key);
+  if (hit && now - hit.at < HUB_READ_TTL_MS) return hit.read as Promise<T>;
+  const fresh = read();
+  hubReads.set(key, { at: now, read: fresh });
+  return fresh;
+}
+
+/** Whether the API accepts a lead; any failed read counts as accepting (as /contact). */
+function readAccepting(): Promise<boolean> {
+  return sharedHubRead("capture-status", async () => {
+    try {
+      const res = await leads.captureStatus();
+      return res.ok && res.body.ok === true ? res.body.data.contact : true;
+    } catch {
+      return true;
+    }
+  });
+}
+
+/** The served Job application magnet's config, or `null` for any failed read. */
+function readJobApplicationMagnet(): Promise<FlowConfig | null> {
+  return sharedHubRead("job-application-magnet", async () => {
+    try {
+      const res = await flows.get(JOB_APPLICATION_FLOW_SLUG);
+      return res.ok ? res.body : null;
+    } catch {
+      return null;
+    }
+  });
+}
+
 export async function generateMetadata({
   params,
 }: Pick<Props, "params">): Promise<Metadata> {
@@ -23,11 +107,72 @@ export default async function Page({
   getMdxSource,
 }: Props): Promise<ReactElement> {
   const { locale, slug } = await params;
-  return renderPage({
+  const rendered = await renderPage({
     type: "JobPosting",
     slug,
     locale,
     bodyMode: "mdx-body",
     ...(getMdxSource !== undefined && { getMdxSource }),
   });
+
+  const [accepting, t, tCareers, magnet] = await Promise.all([
+    readAccepting(),
+    getTranslations({ locale, namespace: "contact" }),
+    getTranslations({ locale, namespace: "careers" }),
+    readJobApplicationMagnet(),
+  ]);
+  const text = contactFormText(t);
+  const contactEmail = readSiteContactEmail();
+  const view =
+    (magnet ? jobApplicationFormFromConfig(magnet, locale) : null) ??
+    jobApplicationFormFallback(locale);
+
+  return (
+    <>
+      {rendered}
+      <section
+        id="apply"
+        aria-labelledby="apply-heading"
+        className="scroll-mt-24"
+        data-testid="job-apply"
+      >
+        <Container className="pb-section">
+          <div className="max-w-container-sm">
+            <Heading level={2} id="apply-heading" className="mb-block-tight">
+              {view.title}
+            </Heading>
+            {accepting ? (
+              <LeadCaptureForm
+                action={captureLeadAction.bind(null, slug)}
+                text={
+                  view.consentStatement
+                    ? { ...text, consentStatement: view.consentStatement }
+                    : text
+                }
+                termsHref={localeHref(locale, "/terms")}
+                policies={{
+                  terms: localeHref(locale, "/terms"),
+                  privacy: localeHref(locale, "/privacy"),
+                  working_agreement: localeHref(locale, "/working-agreement"),
+                }}
+                fallbackEmail={contactEmail}
+                fields={view.fields}
+                submitLabel={view.submitLabel}
+                successMessage={tCareers("applicationSuccess")}
+              />
+            ) : (
+              <ContactFallback
+                email={contactEmail}
+                text={{
+                  heading: text.unavailableHeading,
+                  body: text.unavailableBody,
+                  noEmail: text.unavailableNoEmail,
+                }}
+              />
+            )}
+          </div>
+        </Container>
+      </section>
+    </>
+  );
 }