@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 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
- # Temporary Holding Version
1
+ # @nexus-src/sdk-core
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.
@@ -0,0 +1,11 @@
1
+ {
2
+ "contract": "SDK-PARITY-001",
3
+ "current": "0.1.0",
4
+ "versions": [
5
+ {
6
+ "version": "0.1.0",
7
+ "path": "v0.1.0/sdk-parity.json",
8
+ "sha256": "d9e878a22fdfa6dd5fe9023d4b775b422b9b597c1e7a52ae5442ee277fb53db5"
9
+ }
10
+ ]
11
+ }