@ingram-tech/nk-dev 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/guide.md +23 -12
  2. package/package.json +6 -6
package/guide.md CHANGED
@@ -6,10 +6,12 @@ package. Stay a thin, standard Next.js app (bun · oxlint + oxfmt · strict TS).
6
6
 
7
7
  ## Hard rules
8
8
 
9
- - **Public contact/signup forms MUST use `@ingram-tech/nk-forms`** —
10
- `handleFormSubmission` server-side (rate-limit → bot gate → validate →
11
- escaped-email deliver → uniform 200) and `useFormSubmit` + `HoneypotInput`
12
- client-side. For guarding a *non-form* endpoint (a checkout, an authed
9
+ - **Public contact/signup forms MUST use `@ingram-tech/nk-forms`** — one
10
+ `createFormsHandler` registry at `app/internal/forms/[form]/route.ts`
11
+ (rate-limit → bot gate → validate → escaped-email deliver → uniform 200)
12
+ and `useFormSubmit(formEndpoint(name))` + `HoneypotInput` client-side.
13
+ Forms are plumbing, not API: never mount one under `/api/…` (see Route & URL
14
+ conventions). For guarding a *non-form* endpoint (a checkout, an authed
13
15
  route), call nk-forms' `checkBot` / `verifyHuman` directly instead of the
14
16
  pipeline. Never ship a public form without the bot gate.
15
17
  - **Send email only via `@ingram-tech/nk-email`** — never add another mail client.
@@ -35,10 +37,18 @@ Keep the URL namespace honest about **who calls each route**:
35
37
  that's the redirect URI you register with the IdP. Don't confuse it with
36
38
  *connector* OAuth (the app acting as a client to a provider), which lives at
37
39
  `/internal/connect/<provider>/callback` below.
38
- - **`/api/…` — the app's public API only.** Routes that external clients or your
39
- own frontend consume *as an API*. Nothing else belongs here.
40
- - **`/internal/…` — all plumbing the public never calls as your API.** This is
41
- where provider integrations, webhooks, workers and crons live:
40
+ - **`/api/…` — the app's public API contract, and nothing else.** Routes that
41
+ are a *contract*: versioned, documented (OpenAPI via `nk-api`), something an
42
+ external client or a typed frontend client could build on. The test is not
43
+ "does the frontend fetch it" but "would we owe someone a deprecation if it
44
+ changed". A form POST with one React consumer fails that test.
45
+ - **`/internal/…` — everything the app owns and nobody may build on.** Provider
46
+ integrations, webhooks, workers, crons, and the site's own forms:
47
+ - **`/internal/forms/<name>`** — public contact/signup forms, served by one
48
+ `createFormsHandler` registry from `@ingram-tech/nk-forms`. GET mints the
49
+ timing token, POST submits. This is the one anonymous, browser-called
50
+ thing under `/internal`: it is gated by the bot layers and the site's rate
51
+ limiter, **not** by the worker secret. Don't add one.
42
52
  - **`/internal/connect/<provider>/{start,callback}`** — the outbound OAuth /
43
53
  app-install handshake. `start` (session-gated) kicks off the redirect to the
44
54
  provider; **`callback` is the URL you register with the provider** — it
@@ -52,9 +62,10 @@ Keep the URL namespace honest about **who calls each route**:
52
62
  scheduled jobs, gated by a shared worker secret (Vercel Cron / queue calls them).
53
63
 
54
64
  Rule of thumb: if a human navigates to it, it's a **page** (normal route tree);
55
- if your frontend fetches it as an API, it's **`/api/…`**; if a provider, cron, or
56
- queue calls it, it's **`/internal/…`**. Never put OAuth callbacks or webhooks in
57
- the UI/page tree, and never expose internal plumbing under `/api/`.
65
+ if it's a contract someone else could build on, it's **`/api/…`**; if only this
66
+ app's own code, a provider, a cron, or a queue calls it, it's **`/internal/…`**.
67
+ Never put OAuth callbacks or webhooks in the UI/page tree, and never expose
68
+ internal plumbing — forms included — under `/api/`.
58
69
 
59
70
  ## Data & migrations
60
71
 
@@ -154,7 +165,7 @@ tool instead). One-off single-file edits: just edit the file.
154
165
  - `@ingram-tech/nk-db` — Postgres data layer: `createPool` (one TLS-aware pool) + `createQueries` (raw SQL) + `createDb` (Drizzle), the PGlite dev/test harness at `@ingram-tech/nk-db/pglite`, the prefixed-id codec (the standalone `id758` package) at `@ingram-tech/nk-db/id`, and the drift-aware migration runner at `@ingram-tech/nk-db/migrate`
155
166
  - `@ingram-tech/nk-api` — the standard HTTP API seam (Hono + `@hono/zod-openapi`): one `{ error, details? }` envelope, `createApiApp` / `createRouter`, auth + multi-tenant resource-scope middleware, pagination helpers, and an emitted OpenAPI/Swagger doc. Reach for it instead of hand-rolling route handlers
156
167
  - `@ingram-tech/nk-billing` — Stripe primitives: subscriptions, a Stripe-side wallet, and an optional Postgres credit ledger behind the `/credits` subpath. Prices resolve at runtime by Stripe `lookup_key` — **never hardcode a price id**, so test and live share one code path
157
- - `@ingram-tech/nk-forms` — the public contact/signup submission pipeline: `handleFormSubmission` (rate-limit → bot gate → validate → escaped-email deliver → uniform 200), `renderNotificationEmail`, `mintFormToken`, and `useFormSubmit` / `HoneypotInput` (`/react`). It owns the invisible bot-protection layers too (honeypot + signed timing token + Vercel BotID); `verifyHuman` / `checkBot` are exported from the root for non-form endpoints
168
+ - `@ingram-tech/nk-forms` — the public contact/signup submission pipeline: `createFormsHandler` + `defineForm` (one registry at `/internal/forms/[form]`; each entry runs rate-limit → bot gate → validate → escaped-email deliver → uniform 200), `renderNotificationEmail`, and `useFormSubmit(formEndpoint(name))` / `HoneypotInput` (`/react`); `handleFormSubmission` / `mintFormToken` for a standalone route. It owns the invisible bot-protection layers too (honeypot + signed timing token + Vercel BotID); `verifyHuman` / `checkBot` are exported from the root for non-form endpoints
158
169
  - `@ingram-tech/nk-i18n` — type-safe, English-as-key i18n: the English source text *is* the key (no `en.json`), ICU MessageFormat, colocated JSON catalogs, plus **locale URL routing** (`defineLocaleRouting` + a fixed URL→account→cookie→`Accept-Language`→country precedence, wired to Next at `/next`). A URL that names a locale must serve it with a 200 — never redirect `?hl=fr` away, or every hreflang annotation on the site points at a URL that doesn't serve the language it claims. See `docs/i18n-routing.md`
159
170
  - `@ingram-tech/nk-marketing` — Postgres-backed marketing & lifecycle email: contacts + consent, newsletter broadcast audiences, and idempotent triggered campaigns, with RFC 8058 one-click unsubscribe
160
171
  - `@ingram-tech/nk-seo` — SEO toolkit: metadata factory, JSON-LD builders, sitemap/robots routes, hreflang + canonical links, and an OG image template
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ingram-tech/nk-dev",
3
- "version": "0.14.0",
3
+ "version": "0.15.0",
4
4
  "description": "The nextkit dev toolchain in one package: the `nk` CLI plus shared oxlint/oxfmt, TypeScript, and Vitest config, the format-on-commit hook, and the AI agent guide. `nk init` scaffolds a site to use it.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -45,16 +45,16 @@
45
45
  "test": "vitest run"
46
46
  },
47
47
  "dependencies": {
48
- "@ast-grep/cli": "^0.45.1",
48
+ "@ast-grep/cli": "^0.45.3",
49
49
  "@testing-library/dom": "^10.4.1",
50
50
  "@testing-library/jest-dom": "^7.0.1",
51
51
  "@typescript/native": "npm:typescript@^7.0.2",
52
52
  "jsdom": "^30.0.1",
53
- "knip": "^6.32.2",
54
- "oxfmt": "^0.63.0",
55
- "oxlint": "^1.78.0",
53
+ "knip": "^6.34.0",
54
+ "oxfmt": "^0.66.0",
55
+ "oxlint": "^1.81.0",
56
56
  "typescript": "npm:@typescript/typescript6@^6.0.2",
57
- "vitest": "^4.1.10"
57
+ "vitest": "^5.0.0"
58
58
  },
59
59
  "engines": {
60
60
  "node": "^22.22.2 || ^24.15.0 || >=26.0.0"