@nexus-src/sdk-core 0.0.0-stage → 1.0.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/CHANGELOG.md ADDED
@@ -0,0 +1,11 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ ## 1.0.0
6
+
7
+ - Initial release.
8
+ - Environment-neutral transport and error interfaces.
9
+ - Shared auth, entity, custom query, Function, and integration modules.
10
+ - Safe path encoding and structural response validation.
11
+ - 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,72 @@
1
- # Temporary Holding Version
1
+ # nexus-core-sdk
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
+ Contratos TypeScript e módulos de API neutros de ambiente (entidades, custom queries, Functions, integrações e usuário atual), compartilhados pelos SDKs JavaScript da plataforma. É dependência de `@nexus-src/platform-sdk` (browser) e `@nexus-src/functions-sdk` (Server Functions); código de app instala um desses, não o Core.
4
+
5
+ ## Instalação
6
+
7
+ ```bash
8
+ npm install @nexus-src/sdk-core@1.0.0
9
+ ```
10
+
11
+ Node 18 ou mais novo. Publicado em ESM e CommonJS, com tipos para os dois. Sem dependências de runtime.
12
+
13
+ ## Configuração
14
+
15
+ `createSdkCore(options)` recebe:
16
+
17
+ | Opção | Obrigatória | Uso |
18
+ | --------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
19
+ | `transports` | sim | um `Transport` por serviço: `auth` (IAM), `dataManager`, `functions` e `integration`. Cada um recebe o path local do serviço e devolve o payload já parseado |
20
+ | `getDataSourceId` | sim | lido a cada custom query; `undefined` faz a query falhar antes de sair a requisição |
21
+ | `functions.executeInvocationType` | não | `sync` ou `async`, enviado em `X-Invocation-Type` por `functions.execute`. Sem valor, o header não vai e vale o default do servidor |
22
+ | `functions.emptyInput` | não | `empty-object` (padrão) envia `{ "input": {} }` quando não há input; `omit-body` não envia corpo |
23
+ | `errors` | não | `SdkCoreErrorFactory` para o SDK concreto lançar as próprias classes de erro |
24
+
25
+ ## Uso
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
+ O transporte é responsabilidade do SDK concreto: URL base (`/iam`, `/data-manager`, `/functions` e `/integrations` no gateway), autenticação, serialização, timeout, redirect e erro HTTP. O Core não tem `fetch`, não lê variável de ambiente e nunca vê credencial.
45
+
46
+ ## Contratos e armadilhas
47
+
48
+ - Custom query envia `dataSourceId` e `parameters` num único POST e não tenta de novo com outro corpo, porque a primeira requisição já pode ter executado.
49
+ - `core.entities.Task` resolve qualquer propriedade como nome de tabela. Uma tabela chamada `getTable` só é alcançável por `getTable("getTable")`.
50
+ - `deleteMany({})` é recusado com erro de configuração, para não apagar a tabela inteira por engano.
51
+ - Segmento de path vazio, `.` ou `..` é recusado antes da requisição; o resto passa por `encodeURIComponent`.
52
+ - Registro de entidade é validado só como objeto, sem checar o schema da tabela. Usuário, execução, query e integração checam os campos obrigatórios; campo extra passa.
53
+ - `contracts/` guarda o corpus versionado do SDK-PARITY-001, usado pelos SDKs JavaScript e Python e pelo MCP. Mudar uma fixture exige atualizar o SHA-256 no `manifest.json`; veja [contracts/README.md](contracts/README.md).
54
+
55
+ ## Erros
56
+
57
+ | Classe | Quando |
58
+ | --------------------------- | ------------------------------------------------------------------------------ |
59
+ | `SdkCoreConfigurationError` | entrada inválida: path vazio, `deleteMany` sem filtro, query sem data source |
60
+ | `SdkCoreResponseError` | resposta fora do contrato; `code` é `INVALID_RESPONSE` e `retryable` é `false` |
61
+
62
+ Com `errors` configurado, as duas situações lançam o que a factory devolver.
63
+
64
+ ## Desenvolvimento
65
+
66
+ ```bash
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.
@@ -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
+ }