@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.
Files changed (3) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/README.md +31 -37
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,10 @@
2
2
 
3
3
  All notable changes to this project are documented in this file.
4
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
+
5
9
  ## 1.0.0
6
10
 
7
11
  - Initial release.
package/README.md CHANGED
@@ -1,28 +1,28 @@
1
- # nexus-core-sdk
1
+ # @nexus-src/sdk-core
2
2
 
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.
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
- ## Instalação
5
+ ## Installation
6
6
 
7
7
  ```bash
8
- npm install @nexus-src/sdk-core@1.0.0
8
+ npm install @nexus-src/sdk-core
9
9
  ```
10
10
 
11
- Node 18 ou mais novo. Publicado em ESM e CommonJS, com tipos para os dois. Sem dependências de runtime.
11
+ Requires Node 18 or later. Ships ESM and CommonJS builds, with types for both, and has no runtime dependencies.
12
12
 
13
- ## Configuração
13
+ ## Configuration
14
14
 
15
- `createSdkCore(options)` recebe:
15
+ `createSdkCore(options)` takes:
16
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 |
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
- ## Uso
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
- 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.
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
- ## Contratos e armadilhas
46
+ ## Behavior to know
47
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).
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
- ## Erros
55
+ ## Errors
56
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` |
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
- Com `errors` configurado, as duas situações lançam o que a factory devolver.
62
+ With `errors` configured, both cases throw whatever the factory returns.
63
63
 
64
- ## Desenvolvimento
64
+ ## Contributing
65
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.
66
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nexus-src/sdk-core",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Environment-neutral contracts and modules shared by the platform JavaScript SDKs",
5
5
  "type": "module",
6
6
  "sideEffects": false,