@nexus-src/sdk-core 0.0.0-stage → 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 +15 -0
- package/LICENSE +21 -0
- package/README.md +65 -2
- package/contracts/README.md +31 -0
- package/contracts/manifest.json +11 -0
- package/contracts/v0.1.0/sdk-parity.json +783 -0
- package/dist/index.cjs +439 -0
- package/dist/index.d.cts +164 -0
- package/dist/index.d.ts +164 -0
- package/dist/index.js +400 -0
- package/package.json +81 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented in this file.
|
|
4
|
+
|
|
5
|
+
## 1.0.1
|
|
6
|
+
|
|
7
|
+
- README in English, the language of the package page on npm. Maintenance notes moved to CONTRIBUTING.md, outside the package.
|
|
8
|
+
|
|
9
|
+
## 1.0.0
|
|
10
|
+
|
|
11
|
+
- Initial release.
|
|
12
|
+
- Environment-neutral transport and error interfaces.
|
|
13
|
+
- Shared auth, entity, custom query, Function, and integration modules.
|
|
14
|
+
- Safe path encoding and structural response validation.
|
|
15
|
+
- The canonical SDK parity fixture with the MCP, JavaScript, and Python matrix.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Nexus Platform
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,66 @@
|
|
|
1
|
-
#
|
|
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
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @nexus-src/sdk-core
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Requires Node 18 or later. Ships ESM and CommonJS builds, with types for both, and has no runtime dependencies.
|
|
12
|
+
|
|
13
|
+
## Configuration
|
|
14
|
+
|
|
15
|
+
`createSdkCore(options)` takes:
|
|
16
|
+
|
|
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
|
+
|
|
25
|
+
## Usage
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
import { createSdkCore, type Transport } from "@nexus-src/sdk-core"
|
|
29
|
+
|
|
30
|
+
declare const iam: Transport
|
|
31
|
+
declare const dataManager: Transport
|
|
32
|
+
declare const functions: Transport
|
|
33
|
+
declare const integration: Transport
|
|
34
|
+
|
|
35
|
+
const core = createSdkCore({
|
|
36
|
+
transports: { auth: iam, dataManager, functions, integration },
|
|
37
|
+
getDataSourceId: () => undefined,
|
|
38
|
+
functions: { executeInvocationType: "sync", emptyInput: "empty-object" },
|
|
39
|
+
})
|
|
40
|
+
|
|
41
|
+
const tasks = await core.entities.getTable("Task").list({ limit: 20 })
|
|
42
|
+
```
|
|
43
|
+
|
|
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
|
+
|
|
46
|
+
## Behavior to know
|
|
47
|
+
|
|
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
|
+
|
|
55
|
+
## Errors
|
|
56
|
+
|
|
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
|
+
|
|
62
|
+
With `errors` configured, both cases throw whatever the factory returns.
|
|
63
|
+
|
|
64
|
+
## Contributing
|
|
65
|
+
|
|
66
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Contract fixtures
|
|
2
|
+
|
|
3
|
+
`manifest.json` discovers the current SDK-PARITY-001 contract and every packaged
|
|
4
|
+
version. Each entry pins the exact fixture bytes with SHA-256. The versioned
|
|
5
|
+
fixtures record the semantic MCP to JavaScript to Python mapping and the request,
|
|
6
|
+
response, and error cases shared by the SDK test suites.
|
|
7
|
+
|
|
8
|
+
The fixture is source data, not a public JavaScript API. A breaking fixture
|
|
9
|
+
change requires a new version directory. Consumers may vendor the exact bytes
|
|
10
|
+
and pin their copy with a SHA-256 digest so their tests never depend on network
|
|
11
|
+
access.
|
|
12
|
+
|
|
13
|
+
Core executes one success case for every operation plus Core-owned response
|
|
14
|
+
validation cases. Functions JavaScript inherits those checks from Core and must
|
|
15
|
+
consume every HTTP adapter case itself. Python does not depend on Core, so it
|
|
16
|
+
must consume every success, response-validation, and HTTP adapter case. The
|
|
17
|
+
consumer requirements in the fixture make those obligations machine-readable.
|
|
18
|
+
|
|
19
|
+
## Custom query transition
|
|
20
|
+
|
|
21
|
+
The `customQueryTransition` section intentionally models two different server
|
|
22
|
+
contracts:
|
|
23
|
+
|
|
24
|
+
- Data Manager `main` consumes `dataSourceId` and `parameters`.
|
|
25
|
+
- Data Manager `alpha` accepts that same body, ignores `dataSourceId` during
|
|
26
|
+
deserialization, and resolves the data source from the authenticated app.
|
|
27
|
+
|
|
28
|
+
The current SDK release still targets `main`, but its body is transport-compatible
|
|
29
|
+
with the recorded `alpha` contract. The semantics differ because alpha ignores
|
|
30
|
+
the supplied identifier. Do not add an automatic POST fallback because the first
|
|
31
|
+
request can already execute and a retry could execute the query twice.
|