@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 +11 -0
- package/LICENSE +21 -0
- package/README.md +71 -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,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
|
-
#
|
|
1
|
+
# nexus-core-sdk
|
|
2
2
|
|
|
3
|
-
|
|
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.
|