@nexus-src/sdk-core 1.0.0 → 1.0.1
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/CHANGELOG.md +4 -0
- package/README.md +31 -37
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -1,28 +1,28 @@
|
|
|
1
|
-
# nexus-core
|
|
1
|
+
# @nexus-src/sdk-core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Environment-neutral TypeScript contracts and API modules (entities, custom queries, Functions, integrations and the current user) shared by the platform's JavaScript SDKs. It is a dependency of `@nexus-src/platform-sdk` (browser) and `@nexus-src/functions-sdk` (Server Functions); app code installs one of those, not Core.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
npm install @nexus-src/sdk-core
|
|
8
|
+
npm install @nexus-src/sdk-core
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
Node 18
|
|
11
|
+
Requires Node 18 or later. Ships ESM and CommonJS builds, with types for both, and has no runtime dependencies.
|
|
12
12
|
|
|
13
|
-
##
|
|
13
|
+
## Configuration
|
|
14
14
|
|
|
15
|
-
`createSdkCore(options)`
|
|
15
|
+
`createSdkCore(options)` takes:
|
|
16
16
|
|
|
17
|
-
|
|
|
18
|
-
| --------------------------------- |
|
|
19
|
-
| `transports` |
|
|
20
|
-
| `getDataSourceId` |
|
|
21
|
-
| `functions.executeInvocationType` |
|
|
22
|
-
| `functions.emptyInput` |
|
|
23
|
-
| `errors` |
|
|
17
|
+
| Option | Required | Description |
|
|
18
|
+
| --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
19
|
+
| `transports` | yes | One `Transport` per service: `auth` (IAM), `dataManager`, `functions` and `integration`. Each receives the service-local path and returns the parsed payload |
|
|
20
|
+
| `getDataSourceId` | yes | Read on every custom query; `undefined` fails the query before any request is sent |
|
|
21
|
+
| `functions.executeInvocationType` | no | `sync` or `async`, sent as `X-Invocation-Type` by `functions.execute`. When unset, the header is omitted and the server default applies |
|
|
22
|
+
| `functions.emptyInput` | no | `empty-object` (default) sends `{ "input": {} }` when there is no input; `omit-body` sends no body |
|
|
23
|
+
| `errors` | no | An `SdkCoreErrorFactory`, so the concrete SDK can throw its own error classes |
|
|
24
24
|
|
|
25
|
-
##
|
|
25
|
+
## Usage
|
|
26
26
|
|
|
27
27
|
```typescript
|
|
28
28
|
import { createSdkCore, type Transport } from "@nexus-src/sdk-core"
|
|
@@ -41,32 +41,26 @@ const core = createSdkCore({
|
|
|
41
41
|
const tasks = await core.entities.getTable("Task").list({ limit: 20 })
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
Transport belongs to the concrete SDK: base URL (`/iam`, `/data-manager`, `/functions` and `/integrations` on the gateway), authentication, serialization, timeouts, redirects and HTTP errors. Core has no `fetch`, reads no environment variable and never sees a credential.
|
|
45
45
|
|
|
46
|
-
##
|
|
46
|
+
## Behavior to know
|
|
47
47
|
|
|
48
|
-
-
|
|
49
|
-
- `core.entities.Task`
|
|
50
|
-
- `deleteMany({})`
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
- `contracts/`
|
|
48
|
+
- A custom query sends `dataSourceId` and `parameters` in a single POST and never retries with a different body, because the first request may already have run.
|
|
49
|
+
- `core.entities.Task` resolves any property as a table name. A table named `getTable` is only reachable through `getTable("getTable")`.
|
|
50
|
+
- `deleteMany({})` is rejected with a configuration error, so a missing filter cannot delete a whole table.
|
|
51
|
+
- An empty, `.` or `..` path segment is rejected before the request; everything else goes through `encodeURIComponent`.
|
|
52
|
+
- Entity records are only checked to be objects, not against the table schema. Users, executions, queries and integrations are checked for their required fields; extra fields pass through.
|
|
53
|
+
- `contracts/` holds the versioned SDK-PARITY-001 corpus used by the JavaScript and Python SDKs and by the MCP server. Changing a fixture requires updating its SHA-256 in `manifest.json`; see [contracts/README.md](contracts/README.md).
|
|
54
54
|
|
|
55
|
-
##
|
|
55
|
+
## Errors
|
|
56
56
|
|
|
57
|
-
|
|
|
58
|
-
| --------------------------- |
|
|
59
|
-
| `SdkCoreConfigurationError` |
|
|
60
|
-
| `SdkCoreResponseError` |
|
|
57
|
+
| Class | When |
|
|
58
|
+
| --------------------------- | --------------------------------------------------------------------------------------------- |
|
|
59
|
+
| `SdkCoreConfigurationError` | Invalid input: empty path segment, `deleteMany` without a filter, query without a data source |
|
|
60
|
+
| `SdkCoreResponseError` | A response outside the contract; `code` is `INVALID_RESPONSE` and `retryable` is `false` |
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
With `errors` configured, both cases throw whatever the factory returns.
|
|
63
63
|
|
|
64
|
-
##
|
|
64
|
+
## Contributing
|
|
65
65
|
|
|
66
|
-
|
|
67
|
-
npm run check
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
## Publicação
|
|
71
|
-
|
|
72
|
-
Pelo workflow `Publish`, disparado à mão na `main`. Ele publica no npm a versão do `package.json`, que muda por PR, e recusa versão que já existe no registro. Roda antes o `prepublishOnly` do pacote, publica por publicador confiável do npm (OIDC, sem token guardado) e marca o commit com a tag `v<versão>`. A primeira versão de um pacote que ainda não existe no npm sai com `bootstrap` marcado: o workflow faz `npm stage publish` com o segredo `NPM_BOOTSTRAP_TOKEN` do repo, e ela só fica pública quando um mantenedor aprova com 2FA em npmjs.com. Depois disso o publicador confiável é configurado no pacote e o token é apagado.
|
|
66
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|