@farm.js/unkey 0.1.49 → 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 +94 -3
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,11 +1,102 @@
1
1
  # @farm.js/unkey
2
2
 
3
- Unkey integration for Farm.js
3
+ API keys for Farm.js applications, backed by Unkey. The integration gives server code typed calls to
4
+ create, verify, update, revoke, and delete keys, and can verify the key on matching requests before
5
+ they reach a page or API route.
4
6
 
5
7
  See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
6
8
 
9
+ ## Install
10
+
7
11
  ```bash
8
- npm install @farm.js/unkey
12
+ pnpm add @farm.js/unkey
13
+ ```
14
+
15
+ The package has no SDK dependency: it calls Unkey's HTTP API with `fetch`. To scaffold the registry
16
+ entry, a protected API route, and a test page at `/integrations/unkey` in an existing app, run
17
+ `farm add integration unkey --ui`.
18
+
19
+ ## Configure
20
+
21
+ ```ts
22
+ // src/lib/integrations.ts
23
+ import { unkey } from "@farm.js/unkey";
24
+
25
+ export const appIntegrations = {
26
+ apiKeys: unkey({
27
+ protectedRoutes: ["/api/protected(.*)"],
28
+ protection: { permissions: "documents.read" },
29
+ }),
30
+ } as const;
31
+ ```
32
+
33
+ | Variable | Purpose |
34
+ | ---------------- | -------------------------------------------------------------- |
35
+ | `UNKEY_ROOT_KEY` | Root key for the Unkey API. Required unless `instance` is set. |
36
+ | `UNKEY_API_ID` | API that new keys are created in. |
37
+ | `UNKEY_BASE_URL` | Unkey API origin. Defaults to `https://api.unkey.com`. |
38
+
39
+ `rootKey`, `apiId`, `baseUrl`, and `fetch` can be passed as options instead. Keep the root key in
40
+ server-only environment variables.
41
+
42
+ ## Manage keys from server code
43
+
44
+ The `create`, `verify`, `update`, `revoke`, and `delete-key` routes mount under `/api/unkey` and are
45
+ server-only. They answer in-process calls through `api` from `createIntegrations`, and a plain HTTP
46
+ request to them gets `404`, so the root key is never reachable from the browser.
47
+
48
+ ```ts
49
+ // a server-only module
50
+ import { api } from "./api";
51
+
52
+ const created = await api.apiKeys.create({
53
+ body: { externalId: user.id, permissions: ["documents.read"] },
54
+ });
55
+
56
+ const verified = await api.apiKeys.verify({
57
+ body: { key: created.data!.key, permissions: "documents.read" },
58
+ });
9
59
  ```
10
60
 
11
- See the [Farm.js repository](https://github.com/farming-labs/farm.js) for documentation, examples, and support.
61
+ Creating a key needs an API id from `UNKEY_API_ID`, the `apiId` option, or `body.apiId`, and the
62
+ route answers `400` without one. `paths.basePath` moves every route, and `paths.create` and its
63
+ siblings move one.
64
+
65
+ ## Protect routes
66
+
67
+ When a request matches `protectedRoutes` (or `protection.matcher`), the key is verified before the
68
+ handler runs.
69
+
70
+ - The key is read from `authorization`, with or without a `Bearer` prefix, then from `x-api-key`.
71
+ Set `protection.headers` to read other headers.
72
+ - `protection.permissions` and `protection.tags` are checked as part of verification.
73
+ - A missing or invalid key gets `401` with a `code`, and a rate limited key gets `429`.
74
+ `protection.onDenied` can return a response of its own.
75
+ - A verified result is stored in request context as `unkey` (or `protection.contextKey`) and
76
+ `apiKey`, plus `apiKeyId` and `apiKeyOwnerId` when Unkey returns them. Set
77
+ `protection.exposeToPage` to make them readable from pages. `protection.onVerified` can return a
78
+ response instead of continuing.
79
+
80
+ ## Bring your own client
81
+
82
+ ```ts
83
+ import { createUnkeyClient, unkey } from "@farm.js/unkey";
84
+
85
+ const unkeyClient = createUnkeyClient({
86
+ rootKey: process.env.UNKEY_ROOT_KEY,
87
+ apiId: process.env.UNKEY_API_ID,
88
+ });
89
+
90
+ export const apiKeys = unkey({ instance: unkeyClient });
91
+ ```
92
+
93
+ `instance` accepts any object implementing the exported `UnkeyClient` interface, which also suits
94
+ test doubles. With an instance, Farm no longer requires `UNKEY_ROOT_KEY`. The older `client` option
95
+ is a deprecated alias for `instance`.
96
+
97
+ ## Documentation
98
+
99
+ - [Unkey integration](https://farmjs.dev/docs/integrations/unkey)
100
+
101
+ Report issues and find examples in the
102
+ [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/unkey",
3
- "version": "0.1.49",
3
+ "version": "0.1.51-beta.0",
4
4
  "description": "Unkey integration for Farm.js",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -25,8 +25,8 @@
25
25
  "access": "public"
26
26
  },
27
27
  "dependencies": {
28
- "@farm.js/core": "0.1.49",
29
- "@farm.js/integration-utils": "0.1.49"
28
+ "@farm.js/core": "0.1.51-beta.0",
29
+ "@farm.js/integration-utils": "0.1.51-beta.0"
30
30
  },
31
31
  "scripts": {
32
32
  "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",