@mitralab.io/sdk-core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 0.1.0
+
+- Add environment-neutral transport and error interfaces.
+- Add shared auth, entity, custom query, Function, and integration modules.
+- Add safe path encoding and structural response validation.
+- Add the canonical SDK parity fixture and testable MCP, JavaScript, and Python matrix.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitra Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# Mitra SDK Core
+
+Environment-neutral TypeScript contracts and API modules shared by Mitra JavaScript SDKs.
+
+Most application and Server Function code should install a concrete SDK instead:
+
+- `@mitralab.io/platform-sdk` for browser applications
+- `@mitralab.io/functions-sdk` for Mitra Server Functions
+
+The core package exists so both SDKs build entity, custom query, Function, integration, and current-user requests from one contract.
+
+The versioned contract corpus in `contracts/` is the canonical source for the
+MCP, JavaScript, and Python capability matrix. Its manifest identifies the
+current fixture and pins every packaged version with SHA-256. Core executes all
+success operations and response validation. Functions JavaScript inherits those
+checks and owns its HTTP adapter cases. Python consumes all case groups because
+it does not depend on Core, using a digest-pinned snapshot so tests stay offline.
+
+## Boundary
+
+The package contains:
+
+- common types and data transfer objects
+- safe path segment encoding
+- structural response validation
+- `auth.me`, entities, queries, Functions, and integration modules
+- a minimal transport interface injected by each concrete SDK
+
+The package does not contain:
+
+- `fetch` or any other HTTP implementation
+- tokens, authorization headers, or environment variables
+- login, sign-up, logout, refresh, browser storage, or auth listeners
+- retry, redirect, timeout, or client lifecycle policy
+
+Those concerns stay in the concrete SDK because browser sessions and Server Function runtime credentials have different security and failure semantics.
+
+## Installation
+
+```bash
+npm install @mitralab.io/sdk-core
+```
+
+Node.js 18 or newer is required. The package has no runtime dependencies.
+
+## Transport contract
+
+SDK adapters provide one transport per service. A transport receives the service-local path and request options, then returns the parsed response payload.
+
+```typescript
+import { createSdkCore, type Transport } from "@mitralab.io/sdk-core"
+
+declare const iam: Transport
+declare const dataManager: Transport
+declare const functions: Transport
+declare const integration: Transport
+
+let dataSourceId: string | undefined
+
+const core = createSdkCore({
+  transports: { auth: iam, dataManager, functions, integration },
+  getDataSourceId: () => dataSourceId,
+  functions: {
+    executeInvocationType: "sync",
+    emptyInput: "empty-object",
+  },
+})
+
+const tasks = await core.entities.getTable("Task").list({ limit: 20 })
+```
+
+The transport owns URL resolution, authentication, serialization, error parsing, redirects, retries, and timeouts. The core never reads or stores credentials.
+
+Custom query requests currently target the Data Manager `main` contract and
+send both `dataSourceId` and `parameters`. The recorded `alpha` contract accepts
+that body but ignores `dataSourceId`, resolving the data source from the
+authenticated app instead. The SDK does not retry this POST with another body
+because the first request can already execute.
+
+## Error mapping
+
+By default, invalid configuration and invalid responses throw `SdkCoreConfigurationError` and `SdkCoreResponseError`. A concrete SDK can inject an `SdkCoreErrorFactory` so these failures keep that SDK's established public error classes.
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+The build produces ESM, CommonJS, `.d.ts`, and `.d.cts` artifacts. Package smoke tests install the generated tarball into a clean consumer and validate both module systems and TypeScript resolution.

package/contracts/README.md

@@ -0,0 +1,31 @@
+# Contract fixtures
+
+`manifest.json` discovers the current SDK-PARITY-001 contract and every packaged
+version. Each entry pins the exact fixture bytes with SHA-256. The versioned
+fixtures record the semantic MCP to JavaScript to Python mapping and the request,
+response, and error cases shared by the SDK test suites.
+
+The fixture is source data, not a public JavaScript API. A breaking fixture
+change requires a new version directory. Consumers may vendor the exact bytes
+and pin their copy with a SHA-256 digest so their tests never depend on network
+access.
+
+Core executes one success case for every operation plus Core-owned response
+validation cases. Functions JavaScript inherits those checks from Core and must
+consume every HTTP adapter case itself. Python does not depend on Core, so it
+must consume every success, response-validation, and HTTP adapter case. The
+consumer requirements in the fixture make those obligations machine-readable.
+
+## Custom query transition
+
+The `customQueryTransition` section intentionally models two different server
+contracts:
+
+- Data Manager `main` consumes `dataSourceId` and `parameters`.
+- Data Manager `alpha` accepts that same body, ignores `dataSourceId` during
+  deserialization, and resolves the data source from the authenticated app.
+
+The current SDK release still targets `main`, but its body is transport-compatible
+with the recorded `alpha` contract. The semantics differ because alpha ignores
+the supplied identifier. Do not add an automatic POST fallback because the first
+request can already execute and a retry could execute the query twice.

package/contracts/manifest.json

@@ -0,0 +1,11 @@
+{
+  "contract": "SDK-PARITY-001",
+  "current": "0.1.0",
+  "versions": [
+    {
+      "version": "0.1.0",
+      "path": "v0.1.0/sdk-parity.json",
+      "sha256": "600be3688cea7cfef16a8cf347516e87949b8e4151efb2c4136a2345557dde70"
+    }
+  ]
+}