@farm.js/integration-utils 0.1.50 → 0.1.51-beta.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/README.md +120 -3
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,11 +1,128 @@
1
1
  # @farm.js/integration-utils
2
2
 
3
- Shared integration utilities for Farm.js
3
+ Provider-neutral helpers for writing Farm.js integrations: config validation that fails at startup,
4
+ webhook definition normalization, request cookie and redirect helpers, auth route scaffolding, and
5
+ typed caller trees inferred from route paths. The first-party integration packages, such as
6
+ `@farm.js/stripe`, `@farm.js/sanity`, and `@farm.js/clerk`, are built on it.
4
7
 
5
8
  See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
6
9
 
10
+ ## Install
11
+
7
12
  ```bash
8
- npm install @farm.js/integration-utils
13
+ pnpm add @farm.js/integration-utils
14
+ ```
15
+
16
+ `@farm.js/core` is a regular dependency. These helpers sit next to `defineIntegration` from
17
+ `@farm.js/core`; application code that only uses integrations does not need this package.
18
+
19
+ ## Usage
20
+
21
+ `integrationConfig` builds the `config` definition `defineIntegration` accepts. Values resolve
22
+ from `defaults`, then the `env` variables, then `input`, and every `required` key that is missing,
23
+ `null`, or empty becomes a startup error such as `Acme integration requires apiKey.`
24
+
25
+ ```ts
26
+ // src/integrations/acme.ts
27
+ import { defineIntegration, integrationRoute } from "@farm.js/core";
28
+ import { integrationConfig } from "@farm.js/integration-utils";
29
+
30
+ type AcmeConfig = { apiKey: string; region: string };
31
+
32
+ export const acme = defineIntegration({
33
+ category: "custom",
34
+ type: "acme",
35
+ instance: {},
36
+ config: integrationConfig<AcmeConfig>({
37
+ label: "Acme integration",
38
+ env: { apiKey: "ACME_API_KEY" },
39
+ defaults: { region: "us" },
40
+ required: ["apiKey"],
41
+ }),
42
+ routes: [
43
+ integrationRoute.get("/api/acme/status", {
44
+ handler() {
45
+ return Response.json({ ok: true });
46
+ },
47
+ }),
48
+ ],
49
+ });
50
+ ```
51
+
52
+ An `env` entry can also be a list, where the first variable that is set wins: `@farm.js/clerk` maps
53
+ `publishableKey` to `["NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY", "CLERK_PUBLISHABLE_KEY"]`.
54
+
55
+ ## Auth routes and webhooks
56
+
57
+ `createAuthRouteIntegration` wraps `defineIntegration` with `category: "auth"` and one route, and
58
+ passes the instance to the handler. `@farm.js/authjs` is written this way:
59
+
60
+ ```ts
61
+ import { createAuthRouteIntegration, methodNotAllowed } from "@farm.js/integration-utils";
62
+
63
+ type AuthJsInstance = {
64
+ handlers: Partial<Record<"GET" | "POST", (request: Request) => Response | Promise<Response>>>;
65
+ };
66
+
67
+ export function authjs(input: { instance: AuthJsInstance }) {
68
+ return createAuthRouteIntegration({
69
+ type: "authjs",
70
+ instance: input.instance,
71
+ path: "/api/auth/[...nextauth]",
72
+ methods: ["GET", "POST"],
73
+ async handler(request, _context, instance) {
74
+ const handler = instance.handlers[request.method.toUpperCase() as "GET" | "POST"];
75
+ return handler ? handler(request) : methodNotAllowed(["GET", "POST"]);
76
+ },
77
+ });
78
+ }
9
79
  ```
10
80
 
11
- See the [Farm.js repository](https://github.com/farming-labs/farm.js) for documentation, examples, and support.
81
+ `normalizeWebhookConfig({ webhooks, defaultName, defaultPath, defaultSecret })` accepts one
82
+ webhook definition or a map of named ones and returns a list with `name`, `path`, and `secret`
83
+ filled in. It throws when a named webhook has no explicit `path` or two webhooks share a path.
84
+ `@farm.js/stripe` and `@farm.js/email` use it for their `webhooks` option.
85
+
86
+ ## Safe defaults
87
+
88
+ - `getReturnTo(value, fallback)` accepts only same-origin, root-relative paths. Values such as
89
+ `//evil.example`, `/\evil.example`, or paths containing a tab, carriage return, or line feed
90
+ return the fallback. `resolveAppPath(path, label)` throws for the same values.
91
+ - `createRequestCookie(name, value, request, options)` defaults to `HttpOnly`, `SameSite=Lax`, and
92
+ `Path=/`, adds `Secure` on HTTPS requests (including `X-Forwarded-Proto: https`), and applies the
93
+ attributes that `__Host-`, `__Secure-`, and `SameSite=None` require. `clearRequestCookie` sends
94
+ the matching deletion.
95
+ - `getCookieValue` and `parseCookieHeaderMap` keep the first value of a repeated cookie name,
96
+ matching `cookies().get(name)` in `@farm.js/core`.
97
+ - `resolveDevelopmentSecret(name)` stores a random 32-byte secret in `.farm/<name>-secret` and
98
+ reuses it across restarts, in place of a constant fallback. Call it only once the environment is
99
+ known to be development; production still needs a real secret.
100
+
101
+ ## Entry points
102
+
103
+ Each subpath below is under `@farm.js/integration-utils`. The package root re-exports the functions
104
+ and webhook types of every subpath except `/dev-secret`.
105
+
106
+ - `/config`: `integrationConfig`
107
+ - `/integration`: `createAuthRouteIntegration`, `methodNotAllowed`, `createPathInferredClientApi`
108
+ - `/webhooks`: `normalizeWebhookConfig` and the `FarmWebhookConfig`, `FarmWebhookDefinition`,
109
+ `FarmWebhookEvent`, `FarmWebhookContext`, and `FarmWebhookAckResult` types
110
+ - `/cookies`: `getCookieValue`, `parseCookieHeaderList`, `parseCookieHeaderMap`,
111
+ `createRequestCookie`, `clearRequestCookie`
112
+ - `/url`: `getOrigin`, `getReturnTo`, `toAbsoluteUrl`, `withSearchParams`, `resolveAppPath`,
113
+ `resolveCallbackSettings`
114
+ - `/matchers`: `normalizeMatchers`, `createDocumentNavigationMatchers`
115
+ - `/html`: `escapeHtml`
116
+ - `/dev-secret`: `resolveDevelopmentSecret`, available only from this subpath
117
+
118
+ `createPathInferredClientApi` derives a typed caller tree from route paths: the `/api/<name>`
119
+ prefix is dropped, kebab-case segments become camelCase, `[param]` becomes `param`, and the HTTP
120
+ method is the leaf. `@farm.js/unkey` builds its `api` this way.
121
+
122
+ ## Documentation
123
+
124
+ - [Custom Integrations](https://farmjs.dev/docs/integrations/custom): `defineIntegration`, routes,
125
+ config validation, lifecycle hooks, and providers.
126
+ - [Integrations](https://farmjs.dev/docs/integrations)
127
+
128
+ Report issues and find examples in the [Farm.js repository](https://github.com/farming-labs/farm.js).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@farm.js/integration-utils",
3
- "version": "0.1.50",
3
+ "version": "0.1.51-beta.0",
4
4
  "description": "Shared integration utilities for Farm.js",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -57,7 +57,7 @@
57
57
  "access": "public"
58
58
  },
59
59
  "dependencies": {
60
- "@farm.js/core": "0.1.50"
60
+ "@farm.js/core": "0.1.51-beta.0"
61
61
  },
62
62
  "scripts": {
63
63
  "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",