@mitralab.io/platform-sdk 1.0.7 → 1.0.9

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## Unreleased
+
+- Make the SonarCloud job wait for the Quality Gate result.
+- Align the public package metadata and ESM, CommonJS, and TypeScript artifacts.
+- Add package shape checks and public tarball smoke coverage.
+- Correct public imports and required configuration in documentation examples.
+- Add the MIT license.
+
+## 1.0.8
+
+- Share environment-neutral API contracts through `@mitralab.io/sdk-core`.
+- Preserve the Platform SDK 1.x browser authentication and entity facade.
+- Validate redirects, API errors, sensitive-value redaction, and package consumers.

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

@@ -3,148 +3,173 @@
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=mitra-platform-sdk&metric=alert_status&token=28d7be14b66d6f88d706347e2418af5ea39ab3e9)](https://sonarcloud.io/summary/new_code?id=mitra-platform-sdk)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=mitra-platform-sdk&metric=coverage&token=28d7be14b66d6f88d706347e2418af5ea39ab3e9)](https://sonarcloud.io/summary/new_code?id=mitra-platform-sdk)
 
-The Mitra Platform SDK provides a JavaScript/TypeScript interface for building apps on the Mitra Platform. When Mitra generates your app, the generated code uses this SDK to authenticate users, manage your app's data, execute serverless functions, and more. You can use the same SDK to modify and extend your app.
+JavaScript and TypeScript SDK for browser applications built on the Mitra Platform. Applications generated by Code Studio use this package to authenticate users, access Data Manager entities, execute Server Functions and custom queries, and call integrations.
 
-**Zero runtime dependencies.** Uses only standard Web APIs (`fetch`, `localStorage`, `URL`, `Proxy`).
-
-## Modules
-
-- **`auth`**: User authentication, registration, and session handling.
-- **`entities`**: Database CRUD operations.
-- **`functions`**: Serverless function execution.
-- **`integration`**: Proxy HTTP requests to external APIs with automatic credential injection.
-- **`queries`**: Execute reusable named queries.
+The browser transport uses standard Web APIs only: `fetch`, `localStorage`, `URL`, and `Proxy`. Shared contracts and API modules come from `@mitralab.io/sdk-core`, without bringing browser authentication into the Core package.
 
 ## Installation
 
 ```bash
-npm install mitra-platform-sdk
+npm install @mitralab.io/platform-sdk
 ```
 
-## Quick Start
+Node.js 18 or newer is required for development and server-side tooling. The runtime application must provide the browser Web APIs used by the SDK.
+
+## Quick start
 
 ```typescript
-import { createClient } from 'mitra-platform-sdk';
+import { createClient } from "@mitralab.io/platform-sdk"
 
-const mitra = createClient({
-  appId: 'your-app-id',
-  apiUrl: 'https://api.mitra.io',
-});
+export const mitra = createClient({
+  appId: import.meta.env.VITE_MITRA_APP_ID,
+  apiUrl: import.meta.env.VITE_MITRA_API_URL,
+  onError: (error) => console.error(error.status, error.code, error.message),
+})
 
-await mitra.init();
+await mitra.init()
 ```
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `appId` | `string` | Yes | Your app's unique identifier |
-| `apiUrl` | `string` | Yes | Base URL of the Mitra API |
-| `onError` | `(error) => void` | No | Global error handler for all API requests |
+`init()` resolves the application's public Code Studio configuration, including `dataSourceId` and `allowSignup`. Call it during application startup before using entities, custom queries, or sign-up.
+
+## Configuration
+
+| Field | Required | Description |
+|---|---|---|
+| `appId` | yes | ID of the published Code Studio application. |
+| `apiUrl` | yes | Base URL of the Mitra API gateway. |
+| `onError` | no | Global callback for API errors. |
+
+The client derives service endpoints from `apiUrl`: `/iam`, `/data-manager`, `/functions`, `/integration`, and `/code-studio`.
+
+## Boundary
 
-`init()` must be called before using the client. Safe to call multiple times.
+The Platform SDK owns:
 
-## Usage
+- browser login, sign-up, logout, and session refresh
+- session persistence in `localStorage`
+- auth-state listeners
+- one retry after a successful token refresh on a `401` response
+- browser HTTP transport and public application initialization
 
-All modules and methods are fully typed — explore the full API through your editor's autocomplete or read the JSDoc in the source code.
+`@mitralab.io/sdk-core` owns the shared entities, custom queries, Functions, integrations, `auth.me`, safe paths, and structural response validation. Server Function code should use `@mitralab.io/functions-sdk` instead of this browser SDK.
 
-### Authentication
+## Authentication
 
 ```typescript
-// Sign up (auto-signs in after registration)
-const user = await mitra.auth.signUp({
-  email: 'user@example.com',
-  password: 'password123',
-  name: 'Jane Doe',
-});
-
-// Sign in
-await mitra.auth.signIn({ email: 'user@example.com', password: 'password123' });
-
-// Check state
-console.log(mitra.auth.isAuthenticated, mitra.auth.currentUser);
-
-// Listen for auth changes (fires immediately with current state)
-const unsubscribe = mitra.auth.onAuthStateChange((user) => {
-  console.log(user ? 'Logged in' : 'Logged out');
-});
-
-// Sign out
-mitra.auth.signOut();
+const user = await mitra.auth.signIn({
+  email: "user@example.com",
+  password: "password123",
+})
+
+const unsubscribe = mitra.auth.onAuthStateChange((currentUser) => {
+  console.log(currentUser?.email)
+})
+
+mitra.auth.signOut("/login")
+unsubscribe()
 ```
 
-### Entities
+Authentication state is stored under `mitra_auth_{appId}`. When an API request returns `401`, the SDK attempts `refreshSession()` once and repeats the request only when refresh succeeds.
+
+## Entities
 
 ```typescript
-const tasks = await mitra.entities.Task.list('-created_at', 10);
+type Task = {
+  id: string
+  title: string
+  status: "pending" | "done"
+}
+
+const tasks = await mitra.entities.getTable<Task>("Task").list({
+  sort: "-created_at",
+  limit: 10,
+  fields: ["id", "title", "status"],
+})
+
+const pending = await mitra.entities.Task.filter({ status: "pending" })
+const created = await mitra.entities.Task.create({ title: "New task" })
+await mitra.entities.Task.update(created.id, { status: "done" })
+await mitra.entities.Task.delete(created.id)
+```
+
+Table names are case-sensitive and must match the Data Manager table name. Record operations use `/api/v1/tables/{table}/records`. Application and tenant scope come from the authenticated context, not from a data source in the path.
 
-const task = await mitra.entities.Task.create({
-  title: 'New task',
-  status: 'pending',
-});
+## Server Functions
 
-await mitra.entities.Task.update(task.id, { status: 'done' });
+```typescript
+const execution = await mitra.functions.execute("function-id", {
+  orderId: "order-123",
+})
 
-await mitra.entities.Task.delete(task.id);
+console.log(execution.id, execution.status)
 ```
 
-### Functions
+The Platform SDK 1.x `execute` method keeps the existing asynchronous API behavior. It does not send `X-Invocation-Type`, so the Functions service applies its default and returns the created execution, normally with `PENDING` status.
+
+## Custom queries
 
 ```typescript
-const execution = await mitra.functions.execute('function-id', {
-  to: 'user@example.com',
-  subject: 'Welcome',
-});
+const result = await mitra.queries.execute("query-id", {
+  status: "active",
+})
 
-console.log(execution.status, execution.output);
+console.log(result.rows, result.affectedRows)
 ```
 
-### Queries
+## Integrations
+
+Execute a predefined resource:
 
 ```typescript
-const result = await mitra.queries.execute('query-id', { status: 'active' });
-console.log(result.rows);
+const result = await mitra.integration.executeResource("resource-id", {
+  description: "Notebook",
+  limit: 10,
+})
 ```
 
-### Integration
+Or execute an integration config directly:
 
 ```typescript
-const result = await mitra.integration.execute('config-id', {
-  method: 'GET',
-  endpoint: '/users',
-});
-console.log(result.status, result.body);
+const result = await mitra.integration.execute("config-id", {
+  method: "GET",
+  endpoint: "/users",
+  queryParams: { limit: "10" },
+})
+
+console.log(result.status, result.body)
 ```
 
-## Error Handling
+Integration credentials are injected by the Integration service. Do not pass provider credentials through browser input.
+
+## Errors and request behavior
 
-All API errors throw `MitraApiError`:
+API failures throw `MitraApiError`:
 
 ```typescript
-import { MitraApiError } from 'mitra-platform-sdk';
+import { MitraApiError } from "@mitralab.io/platform-sdk"
 
 try {
-  await mitra.entities.Task.get('non-existent-id');
+  await mitra.entities.Task.get("missing-id")
 } catch (error) {
   if (error instanceof MitraApiError) {
-    console.error(error.status, error.code, error.message);
+    console.error(error.status, error.code, error.message)
   }
 }
 ```
 
-## Development
+The transport refuses HTTP redirects. Statuses `307` and `308`, opaque redirects, and responses already marked as redirected fail without replay. The only automatic replay is the single request attempted after a successful session refresh on `401`.
+
+Before constructing `MitraApiError`, the SDK recursively redacts the token used by the request and credentials in `Bearer` format from the error message, code, details, arrays, values, and object keys.
 
-### Build the SDK
+## Development
 
 ```bash
 npm install
-npm run build
+npm run check
 ```
 
-### Run tests
-
-```bash
-npm test
-```
+`@mitralab.io/sdk-core@0.1.0` is resolved from the public npm registry and locked by integrity in `package-lock.json`. Do not replace it with a `file:` dependency or a local tarball.
 
-## License
+The build produces ESM, CommonJS, `.d.ts`, and `.d.cts` artifacts. Package checks inspect the public tarball with Are The Types Wrong, install it into an isolated consumer, and validate ESM, CommonJS, and TypeScript resolution.
 
-MIT
+See [CHANGELOG.md](CHANGELOG.md) for release history and [LICENSE](LICENSE) for license terms.