@nacre.work/sdk 0.15.0 → 0.16.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/README.md +76 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,3 +1,78 @@
|
|
|
1
1
|
# @nacre.work/sdk
|
|
2
2
|
|
|
3
|
-
TypeScript
|
|
3
|
+
The TypeScript client for a [Nacre](https://nacre.work) installation — a
|
|
4
|
+
self-hosted knowledge index where **search returns exactly what the caller is
|
|
5
|
+
permitted to see**, and nothing else.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @nacre.work/sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { NacreClient } from '@nacre.work/sdk'
|
|
13
|
+
|
|
14
|
+
const nacre = new NacreClient({ baseUrl: 'https://api.example', token })
|
|
15
|
+
|
|
16
|
+
await nacre.documents.add({
|
|
17
|
+
layer: 'handbook',
|
|
18
|
+
externalId: 'onboarding.md',
|
|
19
|
+
title: 'Onboarding',
|
|
20
|
+
content: text,
|
|
21
|
+
})
|
|
22
|
+
|
|
23
|
+
const hits = await nacre.search('when do new hires get access', { topK: 5 })
|
|
24
|
+
// ^ five results this caller may read. Not five filtered down to two.
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Zero dependencies. `fetch` is in every runtime this targets, and a client for a
|
|
28
|
+
security product is the wrong place to inherit a dependency tree.
|
|
29
|
+
|
|
30
|
+
## What it reaches
|
|
31
|
+
|
|
32
|
+
Every operation in the REST contract: documents, search, layers, workspaces,
|
|
33
|
+
grants, users, groups, service accounts, connections and their permission
|
|
34
|
+
ceilings, embedding providers, reference queries and reindexing, the access log,
|
|
35
|
+
and sign-in. A test compares this client against
|
|
36
|
+
[`docs/openapi.yaml`](https://github.com/nacre-work/nacre/blob/main/docs/openapi.yaml)
|
|
37
|
+
in **both** directions, so an operation in the contract and not here is a build
|
|
38
|
+
failure — and so is a method here reaching something the contract does not
|
|
39
|
+
describe.
|
|
40
|
+
|
|
41
|
+
## Three things that surprise people, and none of them is a bug
|
|
42
|
+
|
|
43
|
+
**`top_k` means `top_k`.** The permission filter runs *inside* the index
|
|
44
|
+
traversal rather than over the results, so asking for ten permitted matches
|
|
45
|
+
returns ten. Nothing over-fetches and trims.
|
|
46
|
+
|
|
47
|
+
**No method takes an organization.** Not as an option, not as an administrator
|
|
48
|
+
override, not anywhere. The organization comes from the token; the server
|
|
49
|
+
refuses a request that names one, which from inside an application would read as
|
|
50
|
+
a bug in this library. Making it unrepresentable is cheaper than explaining it.
|
|
51
|
+
|
|
52
|
+
**`get`-shaped methods answer `undefined`, not an exception, on 404.** The API
|
|
53
|
+
returns the same `404` with the same wording for "no such document" and "not
|
|
54
|
+
yours" — deliberately, so nobody can probe for what exists. There is no
|
|
55
|
+
information here to tell those apart, and `undefined` says exactly what the
|
|
56
|
+
server said.
|
|
57
|
+
|
|
58
|
+
One more, from the model rather than the client: **`write` does not imply
|
|
59
|
+
`read`.** `admin` implies both. An ingest-only service account can write into a
|
|
60
|
+
layer and cannot search back what it wrote. This is the opposite of most
|
|
61
|
+
permission systems and is not something to work around.
|
|
62
|
+
|
|
63
|
+
## Sessions
|
|
64
|
+
|
|
65
|
+
`auth.login` returns tokens rather than mutating the client, so which identity a
|
|
66
|
+
client object holds never depends on call history. Pass `refreshToken` and
|
|
67
|
+
`onTokens` and the client renews itself through its own `fetch` seam — no view
|
|
68
|
+
or call site needs to know a session can expire.
|
|
69
|
+
|
|
70
|
+
## Related
|
|
71
|
+
|
|
72
|
+
| | |
|
|
73
|
+
|---|---|
|
|
74
|
+
| [`@nacre.work/cli`](https://www.npmjs.com/package/@nacre.work/cli) | the `nacre` command, built on this client |
|
|
75
|
+
| [`@nacre.work/mcp`](https://www.npmjs.com/package/@nacre.work/mcp) | the MCP server an agent connects to |
|
|
76
|
+
|
|
77
|
+
Apache 2.0. Documentation, the REST contract and the permission model:
|
|
78
|
+
[github.com/nacre-work/nacre](https://github.com/nacre-work/nacre/tree/main/docs).
|