@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.
- package/guide.md +23 -12
- 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
|
-
`
|
|
11
|
-
escaped-email deliver → uniform 200)
|
|
12
|
-
|
|
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
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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
|
|
56
|
-
queue calls it, it's **`/internal/…`**.
|
|
57
|
-
the UI/page tree, and never expose
|
|
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: `
|
|
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.
|
|
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.
|
|
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.
|
|
54
|
-
"oxfmt": "^0.
|
|
55
|
-
"oxlint": "^1.
|
|
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": "^
|
|
57
|
+
"vitest": "^5.0.0"
|
|
58
58
|
},
|
|
59
59
|
"engines": {
|
|
60
60
|
"node": "^22.22.2 || ^24.15.0 || >=26.0.0"
|