@verentis/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verentis
+
+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,146 @@
+# @verentis/sdk
+
+Verentis SDK — file system access, app framework, and developer tools for building Verentis applications.
+
+## Installation
+
+```bash
+npm install @verentis/sdk
+```
+
+## Quick Start
+
+### Standalone mode (local development)
+
+```ts
+import { createVerentisClient } from '@verentis/sdk'
+
+const client = createVerentisClient({
+  apiUrl: 'https://api.verentis.com',
+  auth: { apiKey: 'vrt_abc123_...' },
+  workspaceId: 'workspace-uuid',
+})
+
+const file = await client.files.get('/documents/report.json')
+```
+
+### Running executions
+
+Run a file in the virtual file system — the platform resolves the right engine from the file type
+(e.g. a `.py` file runs on the Python engine), waits for it, and returns the result:
+
+```ts
+import { createVerentisClient } from '@verentis/sdk'
+
+const client = createVerentisClient({
+  apiUrl: 'https://api.verentis.com',
+  auth: { token: '...' },
+  workspaceId: 'workspace-uuid',
+})
+
+// Run a script and await the result (request-response engines return immediately).
+const execution = await client.executions.runAndWait('/scripts/report.py', {
+  arguments: ['--verbose'],
+  parameters: { month: '2025-01' },
+})
+
+console.log(execution.status)            // 'Completed'
+console.log(execution.result?.stdout)    // engine stdout
+
+// Or trigger and inspect explicitly.
+const started = await client.executions.run('/scripts/report.py')
+const current = await client.executions.get(started.id)
+const logs = await client.executions.logs(started.id)
+await client.executions.cancel(started.id)
+```
+
+
+### iframe mode (inside Verentis workspace)
+
+```ts
+import { createVerentisClient } from '@verentis/sdk'
+
+const client = createVerentisClient()
+await client.whenReady()
+
+const { surface, workspace } = client.context
+
+if (surface === 'file') {
+  const content = await client.files.readContent(client.context.file.path)
+} else {
+  // A manifest-enabled spec.launch surface has workspace context but no file.
+  renderWorkspaceHome(workspace)
+}
+```
+
+`spec.launch` is still iframe mode: the host sends `surface: 'workspace'`, the selected
+`entryPoint`, and no `file`. This is distinct from SDK standalone mode, where you pass `apiUrl`,
+credentials and `workspaceId` yourself.
+
+## API Overview
+
+| Export | Description |
+| --- | --- |
+| `createVerentisClient(options?)` | Factory function — creates a configured `VerentisClient` |
+| `VerentisClient` | Main client class with `files`, `executions`, `settings`, `context`, and `bridge` |
+| `FilesModule` | File operations — get, read, write, move, delete, archive |
+| `ExecutionsModule` | Execution operations — run, execute, get, logs, cancel, wait |
+| `SettingsModule` | Workspace settings — list, get, getValue, set, reset, namespaced |
+| `ContextModule` | Workspace and launch-surface context (populated after init) |
+| `Bridge` | PostMessage transport for iframe ↔ host communication |
+| `HttpTransport` | HTTP client for API requests |
+| `ApiKeyAuth` | Auth strategy using API keys |
+| `TokenAuth` | Auth strategy using bearer tokens |
+| `BridgeAuth` | Auth strategy that receives tokens via the bridge |
+| `matchMimeType` / `findBestMatch` | MIME type matching utilities |
+
+### Workspace settings
+
+Apps whose manifest declares `spec.settings[]` get workspace setting definitions auto-registered
+(namespaced `{manifest-name}.{key}`). Read them with the settings module — the app token needs the
+`fabric.setting.read` / `fabric.setting.read-all` permissions from `spec.permissions`:
+
+```ts
+const settings = client.settings.namespaced('my-app')
+const region = await settings.getValue<string>('region', 'eu')
+```
+
+Secret values never reach the browser: secrets read as `value: null` with `hasValue` reporting
+whether one is configured. Engines receive secrets server-side at execution time instead.
+
+See [docs/api-reference.md](docs/api-reference.md) for full API documentation.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode (rebuild on changes)
+npm run dev
+
+# Type checking
+npm run typecheck
+```
+
+## Versioning
+
+This project uses [GitVersion](https://gitversion.net/) for automatic semantic versioning:
+
+- Commits to `main` produce clean versions (e.g., `0.1.1`, `0.1.2`)
+- Feature branches produce pre-release versions (e.g., `0.2.0-my-feature.1`)
+- Use commit message tags to control version bumps:
+  - `+semver: breaking` or `+semver: major` — major bump
+  - `+semver: feature` or `+semver: minor` — minor bump
+  - `+semver: fix` or `+semver: patch` — patch bump (default)
+  - `+semver: none` or `+semver: skip` — no bump
+
+## License
+
+UNLICENSED — proprietary software.